home *** CD-ROM | disk | FTP | other *** search
Text File | 1994-11-03 | 159.6 KB | 4,208 lines |
- @c Copyright (C) 1988, 1989, 1992, 1993, 1994 Free Software Foundation, Inc.
- @c This is part of the GCC manual.
- @c For copying conditions, see the file gcc.texi.
-
- @node Invoking GCC
- @chapter GNU CC Command Options
- @cindex GNU CC command options
- @cindex command options
- @cindex options, GNU CC command
-
- When you invoke GNU CC, it normally does preprocessing, compilation,
- assembly and linking. The ``overall options'' allow you to stop this
- process at an intermediate stage. For example, the @samp{-c} option
- says not to run the linker. Then the output consists of object files
- output by the assembler.
-
- Other options are passed on to one stage of processing. Some options
- control the preprocessor and others the compiler itself. Yet other
- options control the assembler and linker; most of these are not
- documented here, since you rarely need to use any of them.
-
- @cindex C compilation options
- Most of the command line options that you can use with GNU CC are useful
- for C programs; when an option is only useful with another language
- (usually C++), the explanation says so explicitly. If the description
- for a particular option does not mention a source language, you can use
- that option with all supported languages.
-
- @cindex C++ compilation options
- @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
- options for compiling C++ programs.
-
- @cindex grouping options
- @cindex options, grouping
- The @code{gcc} program accepts options and file names as operands. Many
- options have multiletter names; therefore multiple single-letter options
- may @emph{not} be grouped: @samp{-dr} is very different from @w{@samp{-d
- -r}}.
-
- @cindex order of options
- @cindex options, order
- You can mix options and other arguments. For the most part, the order
- you use doesn't matter. Order does matter when you use several options
- of the same kind; for example, if you specify @samp{-L} more than once,
- the directories are searched in the order specified.
-
- Many options have long names starting with @samp{-f} or with
- @samp{-W}---for example, @samp{-fforce-mem},
- @samp{-fstrength-reduce}, @samp{-Wformat} and so on. Most of
- these have both positive and negative forms; the negative form of
- @samp{-ffoo} would be @samp{-fno-foo}. This manual documents
- only one of these two forms, whichever one is not the default.
-
- @menu
- * Option Summary:: Brief list of all options, without explanations.
- * Overall Options:: Controlling the kind of output:
- an executable, object files, assembler files,
- or preprocessed source.
- * Invoking G++:: Compiling C++ programs.
- * C Dialect Options:: Controlling the variant of C language compiled.
- * C++ Dialect Options:: Variations on C++.
- * Warning Options:: How picky should the compiler be?
- * Debugging Options:: Symbol tables, measurements, and debugging dumps.
- * Optimize Options:: How much optimization?
- * Preprocessor Options:: Controlling header files and macro definitions.
- Also, getting dependency information for Make.
- * Assembler Options:: Passing options to the assembler.
- * Link Options:: Specifying libraries and so on.
- * Directory Options:: Where to find header files and libraries.
- Where to find the compiler executable files.
- * Target Options:: Running a cross-compiler, or an old version of GNU CC.
- * Submodel Options:: Specifying minor hardware or convention variations,
- such as 68010 vs 68020.
- * Code Gen Options:: Specifying conventions for function calls, data layout
- and register usage.
- * Environment Variables:: Env vars that affect GNU CC.
- * Running Protoize:: Automatically adding or removing function prototypes.
- @end menu
-
- @node Option Summary
- @section Option Summary
-
- Here is a summary of all the options, grouped by type. Explanations are
- in the following sections.
-
- @table @emph
- @item Overall Options
- @xref{Overall Options,,Options Controlling the Kind of Output}.
- @smallexample
- -c -S -E -o @var{file} -pipe -v -x @var{language}
- @end smallexample
-
- @item C Language Options
- @xref{C Dialect Options,,Options Controlling C Dialect}.
- @smallexample
- -ansi -fallow-single-precision -fcond-mismatch -fno-asm
- -fno-builtin -fsigned-bitfields -fsigned-char
- -funsigned-bitfields -funsigned-char -fwritable-strings
- -traditional -traditional-cpp -trigraphs
- @end smallexample
-
- @item C++ Language Options
- @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
- @smallexample
- -fall-virtual -fdollars-in-identifiers -felide-constructors
- -fenum-int-equiv -fexternal-templates -fhandle-signatures
- -fmemoize-lookups -fno-default-inline -fno-strict-prototype
- -fnonnull-objects -fthis-is-variable -nostdinc++
- -traditional +e@var{n}
- @end smallexample
-
- @item Warning Options
- @xref{Warning Options,,Options to Request or Suppress Warnings}.
- @smallexample
- -fsyntax-only -pedantic -pedantic-errors
- -w -W -Wall -Waggregate-return -Wbad-function-cast
- -Wcast-align -Wcast-qual -Wchar-subscript -Wcomment
- -Wconversion -Wenum-clash -Werror -Wformat
- -Wid-clash-@var{len} -Wimplicit -Wimport -Winline
- -Wlarger-than-@var{len} -Wmissing-declarations
- -Wmissing-prototypes -Wnested-externs
- -Wno-import -Woverloaded-virtual -Wparentheses
- -Wpointer-arith -Wredundant-decls -Wreorder -Wreturn-type -Wshadow
- -Wstrict-prototypes -Wswitch -Wsynth -Wtemplate-debugging
- -Wtraditional -Wtrigraphs -Wuninitialized -Wunused
- -Wwrite-strings
- @end smallexample
-
- @item Debugging Options
- @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
- @smallexample
- -a -d@var{letters} -fpretend-float
- -g -g@var{level} -gcoff -gdwarf -gdwarf+
- -ggdb -gstabs -gstabs+ -gxcoff -gxcoff+
- -p -pg -print-file-name=@var{library} -print-libgcc-file-name
- -print-prog-name=@var{program} -save-temps
- @end smallexample
-
- @item Optimization Options
- @xref{Optimize Options,,Options that Control Optimization}.
- @smallexample
- -fcaller-saves -fcse-follow-jumps -fcse-skip-blocks
- -fdelayed-branch -fexpensive-optimizations
- -ffast-math -ffloat-store -fforce-addr -fforce-mem
- -finline-functions -fkeep-inline-functions
- -fno-default-inline -fno-defer-pop -fno-function-cse
- -fno-inline -fno-peephole -fomit-frame-pointer
- -frerun-cse-after-loop -fschedule-insns
- -fschedule-insns2 -fstrength-reduce -fthread-jumps
- -funroll-all-loops -funroll-loops
- -O -O0 -O1 -O2 -O3
- @end smallexample
-
- @item Preprocessor Options
- @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
- @smallexample
- -A@var{question}(@var{answer}) -C -dD -dM -dN
- -D@var{macro}@r{[}=@var{defn}@r{]} -E -H
- -idirafter @var{dir}
- -include @var{file} -imacros @var{file}
- -iprefix @var{file} -iwithprefix @var{dir}
- -iwithprefixbefore @var{dir} -isystem @var{dir}
- -M -MD -MM -MMD -MG -nostdinc -P -trigraphs
- -undef -U@var{macro} -Wp,@var{option}
- @end smallexample
-
- @item Assembler Option
- @xref{Assembler Options,,Passing Options to the Assembler}.
- @smallexample
- -Wa,@var{option}
- @end smallexample
-
- @item Linker Options
- @xref{Link Options,,Options for Linking}.
- @smallexample
- @var{object-file-name}
- -l@var{library} -nostartfiles -nostdlib
- -s -static -shared -symbolic
- -Wl,@var{option} -Xlinker @var{option}
- -u @var{symbol}
- @end smallexample
-
- @item Directory Options
- @xref{Directory Options,,Options for Directory Search}.
- @smallexample
- -B@var{prefix} -I@var{dir} -I- -L@var{dir}
- @end smallexample
-
- @item Target Options
- @c I wrote this xref this way to avoid overfull hbox. -- rms
- @xref{Target Options}.
- @smallexample
- -b @var{machine} -V @var{version}
- @end smallexample
-
- @item Machine Dependent Options
- @xref{Submodel Options,,Hardware Models and Configurations}.
- @smallexample
- @emph{M680x0 Options}
- -m68000 -m68020 -m68020-40 -m68030 -m68040 -m68881
- -mbitfield -mc68000 -mc68020 -mfpa -mnobitfield
- -mrtd -mshort -msoft-float
-
- @emph{VAX Options}
- -mg -mgnu -munix
-
- @emph{SPARC Options}
- -mapp-regs -mcypress -mepilogue -mflat -mfpu -mhard-float
- -mhard-quad-float -mno-app-regs -mno-flat -mno-fpu
- -mno-epilogue -mno-unaligned-doubles
- -msoft-float -msoft-quad-float
- -msparclite -msupersparc -munaligned-doubles -mv8
-
- SPARC V9 compilers support the following options
- in addition to the above:
-
- -mmedlow -mmedany
- -mint32 -mint64 -mlong32 -mlong64
- -mno-stack-bias -mstack-bias
-
- @emph{Convex Options}
- -mc1 -mc2 -mc32 -mc34 -mc38
- -margcount -mnoargcount
- -mlong32 -mlong64
- -mvolatile-cache -mvolatile-nocache
-
- @emph{AMD29K Options}
- -m29000 -m29050 -mbw -mnbw -mdw -mndw
- -mlarge -mnormal -msmall
- -mkernel-registers -mno-reuse-arg-regs
- -mno-stack-check -mno-storem-bug
- -mreuse-arg-regs -msoft-float -mstack-check
- -mstorem-bug -muser-registers
-
- @emph{ARM Options}
- -mapcs -m2 -m3 -m6 -mbsd -mxopen -mno-symrename
-
- @emph{M88K Options}
- -m88000 -m88100 -m88110 -mbig-pic
- -mcheck-zero-division -mhandle-large-shift
- -midentify-revision -mno-check-zero-division
- -mno-ocs-debug-info -mno-ocs-frame-position
- -mno-optimize-arg-area -mno-serialize-volatile
- -mno-underscores -mocs-debug-info
- -mocs-frame-position -moptimize-arg-area
- -mserialize-volatile -mshort-data-@var{num} -msvr3
- -msvr4 -mtrap-large-shift -muse-div-instruction
- -mversion-03.00 -mwarn-passed-structs
-
- @emph{RS/6000 Options and PowerPC}
- -mcpu=@var{cpu type}
- -mpower -mno-power -mpower2 -pno-power2
- -mpowerpc -mno-powerpc
- -mpowerpc-gpopt -mno-powerpc-gpopt
- -mpowerpc-gfxopt -mno-powerpc-gfxopt
- -mnew-mnemonics -mno-new-mnemonics
- -mfull-toc -mminimal-toc -mno-fop-in-toc -mno-sum-in-toc
-
- @emph{RT Options}
- -mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs
- -mfull-fp-blocks -mhc-struct-return -min-line-mul
- -mminimum-fp-blocks -mnohc-struct-return
-
- @emph{MIPS Options}
- -mabicalls -mcpu=@var{cpu type} -membedded-data
- -membedded-pic -mfp32 -mfp64 -mgas -mgp32 -mgp64
- -mgpopt -mhalf-pic -mhard-float -mint64 -mips1
- -mips2 -mips3 -mlong64 -mlong-calls -mmemcpy
- -mmips-as -mmips-tfile -mno-abicalls
- -mno-embedded-data -mno-embedded-pic
- -mno-gpopt -mno-long-calls
- -mno-memcpy -mno-mips-tfile -mno-rnames -mno-stats
- -mrnames -msoft-float
- -mstats -G @var{num} -nocpp
-
- @emph{i386 Options}
- -m486 -mieee-fp -mno-486 -mno-fancy-math-387
- -mno-fp-ret-in-387 -msoft-float -msvr3-shlib
- -mno-wide-multiply -mreg-alloc=@var{list}
-
- @emph{HPPA Options}
- -mdisable-fpregs -mdisable-indexing -mjump-in-delay
- -mgas -mlong-calls -mno-disable-fpregs -mno-disable-indexing
- -mno-gas -mno-jump-in-delay
- -mno-long-calls -mno-portable-runtime
- -mpa-risc-1-0 -mpa-risc-1-1 -mportable-runtime
-
- @emph{Intel 960 Options}
- -m@var{cpu type} -masm-compat -mclean-linkage
- -mcode-align -mcomplex-addr -mleaf-procedures
- -mic-compat -mic2.0-compat -mic3.0-compat
- -mintel-asm -mno-clean-linkage -mno-code-align
- -mno-complex-addr -mno-leaf-procedures
- -mno-old-align -mno-strict-align -mno-tail-call
- -mnumerics -mold-align -msoft-float -mstrict-align
- -mtail-call
-
- @emph{DEC Alpha Options}
- -mfp-regs -mno-fp-regs -mno-soft-float
- -msoft-float
-
- @emph{Clipper Options}
- -mc300 -mc400
-
- @emph{H8/300 Options}
- -mrelax -mh
-
- @emph{System V Options}
- -Qy -Qn -YP,@var{paths} -Ym,@var{dir}
- @end smallexample
-
- @item Code Generation Options
- @xref{Code Gen Options,,Options for Code Generation Conventions}.
- @smallexample
- -fcall-saved-@var{reg} -fcall-used-@var{reg}
- -ffixed-@var{reg} -finhibit-size-directive
- -fno-common -fno-ident -fno-gnu-linker
- -fpcc-struct-return -fpic -fPIC
- -freg-struct-return -fshared-data -fshort-enums
- -fshort-double -fvolatile -fvolatile-global
- -fverbose-asm +e0 +e1
- @end smallexample
- @end table
-
- @menu
- * Overall Options:: Controlling the kind of output:
- an executable, object files, assembler files,
- or preprocessed source.
- * C Dialect Options:: Controlling the variant of C language compiled.
- * C++ Dialect Options:: Variations on C++.
- * Warning Options:: How picky should the compiler be?
- * Debugging Options:: Symbol tables, measurements, and debugging dumps.
- * Optimize Options:: How much optimization?
- * Preprocessor Options:: Controlling header files and macro definitions.
- Also, getting dependency information for Make.
- * Assembler Options:: Passing options to the assembler.
- * Link Options:: Specifying libraries and so on.
- * Directory Options:: Where to find header files and libraries.
- Where to find the compiler executable files.
- * Target Options:: Running a cross-compiler, or an old version of GNU CC.
- @end menu
-
- @node Overall Options
- @section Options Controlling the Kind of Output
-
- Compilation can involve up to four stages: preprocessing, compilation
- proper, assembly and linking, always in that order. The first three
- stages apply to an individual source file, and end by producing an
- object file; linking combines all the object files (those newly
- compiled, and those specified as input) into an executable file.
-
- @cindex file name suffix
- For any given input file, the file name suffix determines what kind of
- compilation is done:
-
- @table @code
- @item @var{file}.c
- C source code which must be preprocessed.
-
- @item @var{file}.i
- C source code which should not be preprocessed.
-
- @item @var{file}.ii
- C++ source code which should not be preprocessed.
-
- @item @var{file}.m
- Objective-C source code. Note that you must link with the library
- @file{libobjc.a} to make an Objective-C program work.
-
- @item @var{file}.h
- C header file (not to be compiled or linked).
-
- @item @var{file}.cc
- @itemx @var{file}.cxx
- @itemx @var{file}.cpp
- @itemx @var{file}.C
- C++ source code which must be preprocessed. Note that in @samp{.cxx},
- the last two letters must both be literally @samp{x}. Likewise,
- @samp{.C} refers to a literal capital C.
-
- @item @var{file}.s
- Assembler code.
-
- @item @var{file}.S
- Assembler code which must be preprocessed.
-
- @item @var{other}
- An object file to be fed straight into linking.
- Any file name with no recognized suffix is treated this way.
- @end table
-
- You can specify the input language explicitly with the @samp{-x} option:
-
- @table @code
- @item -x @var{language}
- Specify explicitly the @var{language} for the following input files
- (rather than letting the compiler choose a default based on the file
- name suffix). This option applies to all following input files until
- the next @samp{-x} option. Possible values for @var{language} are:
- @example
- c objective-c c++
- c-header cpp-output c++-cpp-output
- assembler assembler-with-cpp
- @end example
-
- @item -x none
- Turn off any specification of a language, so that subsequent files are
- handled according to their file name suffixes (as they are if @samp{-x}
- has not been used at all).
- @end table
-
- If you only want some of the stages of compilation, you can use
- @samp{-x} (or filename suffixes) to tell @code{gcc} where to start, and
- one of the options @samp{-c}, @samp{-S}, or @samp{-E} to say where
- @code{gcc} is to stop. Note that some combinations (for example,
- @samp{-x cpp-output -E} instruct @code{gcc} to do nothing at all.
-
- @table @code
- @item -c
- Compile or assemble the source files, but do not link. The linking
- stage simply is not done. The ultimate output is in the form of an
- object file for each source file.
-
- By default, the object file name for a source file is made by replacing
- the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
-
- Unrecognized input files, not requiring compilation or assembly, are
- ignored.
-
- @item -S
- Stop after the stage of compilation proper; do not assemble. The output
- is in the form of an assembler code file for each non-assembler input
- file specified.
-
- By default, the assembler file name for a source file is made by
- replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
-
- Input files that don't require compilation are ignored.
-
- @item -E
- Stop after the preprocessing stage; do not run the compiler proper. The
- output is in the form of preprocessed source code, which is sent to the
- standard output.
-
- Input files which don't require preprocessing are ignored.
-
- @cindex output file option
- @item -o @var{file}
- Place output in file @var{file}. This applies regardless to whatever
- sort of output is being produced, whether it be an executable file,
- an object file, an assembler file or preprocessed C code.
-
- Since only one output file can be specified, it does not make sense to
- use @samp{-o} when compiling more than one input file, unless you are
- producing an executable file as output.
-
- If @samp{-o} is not specified, the default is to put an executable file
- in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in
- @file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and
- all preprocessed C source on standard output.@refill
-
- @item -v
- Print (on standard error output) the commands executed to run the stages
- of compilation. Also print the version number of the compiler driver
- program and of the preprocessor and the compiler proper.
-
- @item -pipe
- Use pipes rather than temporary files for communication between the
- various stages of compilation. This fails to work on some systems where
- the assembler is unable to read from a pipe; but the GNU assembler has
- no trouble.
- @end table
-
- @node Invoking G++
- @section Compiling C++ Programs
-
- @cindex suffixes for C++ source
- @cindex C++ source file suffixes
- C++ source files conventionally use one of the suffixes @samp{.C},
- @samp{.cc}, @samp{cpp}, or @samp{.cxx}; preprocessed C++ files use the
- suffix @samp{.ii}. GNU CC recognizes files with these names and
- compiles them as C++ programs even if you call the compiler the same way
- as for compiling C programs (usually with the name @code{gcc}).
-
- @findex g++
- @findex c++
- However, C++ programs often require class libraries as well as a
- compiler that understands the C++ language---and under some
- circumstances, you might want to compile programs from standard input,
- or otherwise without a suffix that flags them as C++ programs.
- @code{g++} is a program that calls GNU CC with the default language
- set to C++, and automatically specifies linking against the GNU class
- library libg++.
- @cindex @code{g++ 1.@var{xx}}
- @cindex @code{g++}, separate compiler
- @cindex @code{g++} older version
- @footnote{Prior to release 2 of the compiler,
- there was a separate @code{g++} compiler. That version was based on GNU
- CC, but not integrated with it. Versions of @code{g++} with a
- @samp{1.@var{xx}} version number---for example, @code{g++} version 1.37
- or 1.42---are much less reliable than the versions integrated with GCC
- 2. Moreover, combining G++ @samp{1.@var{xx}} with a version 2 GCC will
- simply not work.} On many systems, the script @code{g++} is also
- installed with the name @code{c++}.
-
- @cindex invoking @code{g++}
- When you compile C++ programs, you may specify many of the same
- command-line options that you use for compiling programs in any
- language; or command-line options meaningful for C and related
- languages; or options that are meaningful only for C++ programs.
- @xref{C Dialect Options,,Options Controlling C Dialect}, for
- explanations of options for languages related to C.
- @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
- explanations of options that are meaningful only for C++ programs.
-
- @node C Dialect Options
- @section Options Controlling C Dialect
- @cindex dialect options
- @cindex language dialect options
- @cindex options, dialect
-
- The following options control the dialect of C (or languages derived
- from C, such as C++ and Objective C) that the compiler accepts:
-
- @table @code
- @cindex ANSI support
- @item -ansi
- Support all ANSI standard C programs.
-
- This turns off certain features of GNU C that are incompatible with ANSI
- C, such as the @code{asm}, @code{inline} and @code{typeof} keywords, and
- predefined macros such as @code{unix} and @code{vax} that identify the
- type of system you are using. It also enables the undesirable and
- rarely used ANSI trigraph feature, and disallows @samp{$} as part of
- identifiers.
-
- The alternate keywords @code{__asm__}, @code{__extension__},
- @code{__inline__} and @code{__typeof__} continue to work despite
- @samp{-ansi}. You would not want to use them in an ANSI C program, of
- course, but it is useful to put them in header files that might be included
- in compilations done with @samp{-ansi}. Alternate predefined macros
- such as @code{__unix__} and @code{__vax__} are also available, with or
- without @samp{-ansi}.
-
- The @samp{-ansi} option does not cause non-ANSI programs to be
- rejected gratuitously. For that, @samp{-pedantic} is required in
- addition to @samp{-ansi}. @xref{Warning Options}.
-
- The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
- option is used. Some header files may notice this macro and refrain
- from declaring certain functions or defining certain macros that the
- ANSI standard doesn't call for; this is to avoid interfering with any
- programs that might use these names for other things.
-
- The functions @code{alloca}, @code{abort}, @code{exit}, and
- @code{_exit} are not builtin functions when @samp{-ansi} is used.
-
- @item -fno-asm
- Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
- keyword. These words may then be used as identifiers. You can use the
- keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
- instead. @samp{-ansi} implies @samp{-fno-asm}.
-
- @item -fno-builtin
- @cindex builtin functions
- @findex abort
- @findex abs
- @findex alloca
- @findex cos
- @findex exit
- @findex fabs
- @findex ffs
- @findex labs
- @findex memcmp
- @findex memcpy
- @findex sin
- @findex sqrt
- @findex strcmp
- @findex strcpy
- @findex strlen
- Don't recognize builtin functions that do not begin with two leading
- underscores. Currently, the functions affected include @code{abort},
- @code{abs}, @code{alloca}, @code{cos}, @code{exit}, @code{fabs},
- @code{ffs}, @code{labs}, @code{memcmp}, @code{memcpy}, @code{sin},
- @code{sqrt}, @code{strcmp}, @code{strcpy}, and @code{strlen}.
-
- GCC normally generates special code to handle certain builtin functions
- more efficiently; for instance, calls to @code{alloca} may become single
- instructions that adjust the stack directly, and calls to @code{memcpy}
- may become inline copy loops. The resulting code is often both smaller
- and faster, but since the function calls no longer appear as such, you
- cannot set a breakpoint on those calls, nor can you change the behavior
- of the functions by linking with a different library.
-
- The @samp{-ansi} option prevents @code{alloca} and @code{ffs} from being
- builtin functions, since these functions do not have an ANSI standard
- meaning.
-
- @item -trigraphs
- Support ANSI C trigraphs. You don't want to know about this
- brain-damage. The @samp{-ansi} option implies @samp{-trigraphs}.
-
- @cindex traditional C language
- @cindex C language, traditional
- @item -traditional
- Attempt to support some aspects of traditional C compilers.
- Specifically:
-
- @itemize @bullet
- @item
- All @code{extern} declarations take effect globally even if they
- are written inside of a function definition. This includes implicit
- declarations of functions.
-
- @item
- The newer keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
- and @code{volatile} are not recognized. (You can still use the
- alternative keywords such as @code{__typeof__}, @code{__inline__}, and
- so on.)
-
- @item
- Comparisons between pointers and integers are always allowed.
-
- @item
- Integer types @code{unsigned short} and @code{unsigned char} promote
- to @code{unsigned int}.
-
- @item
- Out-of-range floating point literals are not an error.
-
- @item
- Certain constructs which ANSI regards as a single invalid preprocessing
- number, such as @samp{0xe-0xd}, are treated as expressions instead.
-
- @item
- String ``constants'' are not necessarily constant; they are stored in
- writable space, and identical looking constants are allocated
- separately. (This is the same as the effect of
- @samp{-fwritable-strings}.)
-
- @cindex @code{longjmp} and automatic variables
- @item
- All automatic variables not declared @code{register} are preserved by
- @code{longjmp}. Ordinarily, GNU C follows ANSI C: automatic variables
- not declared @code{volatile} may be clobbered.
-
- @item
- @kindex \x
- @kindex \a
- @cindex escape sequences, traditional
- The character escape sequences @samp{\x} and @samp{\a} evaluate as the
- literal characters @samp{x} and @samp{a} respectively. Without
- @w{@samp{-traditional}}, @samp{\x} is a prefix for the hexadecimal
- representation of a character, and @samp{\a} produces a bell.
-
- @item
- In C++ programs, assignment to @code{this} is permitted with
- @samp{-traditional}. (The option @samp{-fthis-is-variable} also has
- this effect.)
- @end itemize
-
- You may wish to use @samp{-fno-builtin} as well as @samp{-traditional}
- if your program uses names that are normally GNU C builtin functions for
- other purposes of its own.
-
- You cannot use @samp{-traditional} if you include any header files that
- rely on ANSI C features. Some vendors are starting to ship systems with
- ANSI C header files and you cannot use @samp{-traditional} on such
- systems to compile files that include any system headers.
-
- @item
- In the preprocessor, comments convert to nothing at all, rather than
- to a space. This allows traditional token concatenation.
-
- @item
- In preprocessor directive, the @samp{#} symbol must appear as the first
- character of a line.
-
- @item
- In the preprocessor, macro arguments are recognized within string
- constants in a macro definition (and their values are stringified,
- though without additional quote marks, when they appear in such a
- context). The preprocessor always considers a string constant to end
- at a newline.
-
- @item
- @cindex detecting @w{@samp{-traditional}}
- The predefined macro @code{__STDC__} is not defined when you use
- @samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
- which @code{__GNUC__} indicates are not affected by
- @samp{-traditional}). If you need to write header files that work
- differently depending on whether @samp{-traditional} is in use, by
- testing both of these predefined macros you can distinguish four
- situations: GNU C, traditional GNU C, other ANSI C compilers, and other
- old C compilers. @xref{Standard Predefined,,Standard Predefined
- Macros,cpp.info,The C Preprocessor}, for more discussion of these and other
- predefined macros.
-
- @item
- @cindex string constants vs newline
- @cindex newline vs string constants
- The preprocessor considers a string constant to end at a newline (unless
- the newline is escaped with @samp{\}). (Without @w{@samp{-traditional}},
- string constants can contain the newline character as typed.)
-
- @item -traditional-cpp
- Attempt to support some aspects of traditional C preprocessors.
- This includes the last five items in the table immediately above,
- but none of the other effects of @samp{-traditional}.
-
- @item -fcond-mismatch
- Allow conditional expressions with mismatched types in the second and
- third arguments. The value of such an expression is void.
-
- @item -funsigned-char
- Let the type @code{char} be unsigned, like @code{unsigned char}.
-
- Each kind of machine has a default for what @code{char} should
- be. It is either like @code{unsigned char} by default or like
- @code{signed char} by default.
-
- Ideally, a portable program should always use @code{signed char} or
- @code{unsigned char} when it depends on the signedness of an object.
- But many programs have been written to use plain @code{char} and
- expect it to be signed, or expect it to be unsigned, depending on the
- machines they were written for. This option, and its inverse, let you
- make such a program work with the opposite default.
-
- The type @code{char} is always a distinct type from each of
- @code{signed char} or @code{unsigned char}, even though its behavior
- is always just like one of those two.
-
- @item -fsigned-char
- Let the type @code{char} be signed, like @code{signed char}.
-
- Note that this is equivalent to @samp{-fno-unsigned-char}, which is
- the negative form of @samp{-funsigned-char}. Likewise, the option
- @samp{-fno-signed-char} is equivalent to @samp{-funsigned-char}.
-
- @item -fsigned-bitfields
- @itemx -funsigned-bitfields
- @itemx -fno-signed-bitfields
- @itemx -fno-unsigned-bitfields
- These options control whether a bitfield is signed or unsigned, when the
- declaration does not use either @code{signed} or @code{unsigned}. By
- default, such a bitfield is signed, because this is consistent: the
- basic integer types such as @code{int} are signed types.
-
- However, when @samp{-traditional} is used, bitfields are all unsigned
- no matter what.
-
- @item -fwritable-strings
- Store string constants in the writable data segment and don't uniquize
- them. This is for compatibility with old programs which assume they can
- write into string constants. The option @samp{-traditional} also has
- this effect.
-
- Writing into string constants is a very bad idea; ``constants'' should
- be constant.
-
- @item -fallow-single-precision
- Do not promote single precision math operations to double precision,
- even when compiling with @samp{-traditional}.
-
- Traditional K&R C promotes all floating point operations to double
- precision, regardless of the sizes of the operands. On the
- architecture for which you are compiling, single precision may be faster
- than double precision. If you must use @samp{-traditional}, but want
- to use single precision operations when the operands are single
- precision, use this option. This option has no effect when compiling
- with ANSI or GNU C conventions (the default).
-
- @end table
-
- @node C++ Dialect Options
- @section Options Controlling C++ Dialect
-
- @cindex compiler options, C++
- @cindex C++ options, command line
- @cindex options, C++
- This section describes the command-line options that are only meaningful
- for C++ programs; but you can also use most of the GNU compiler options
- regardless of what language your program is in. For example, you
- might compile a file @code{firstClass.C} like this:
-
- @example
- g++ -g -felide-constructors -O -c firstClass.C
- @end example
-
- @noindent
- In this example, only @samp{-felide-constructors} is an option meant
- only for C++ programs; you can use the other options with any
- language supported by GNU CC.
-
- Here is a list of options that are @emph{only} for compiling C++ programs:
-
- @table @code
- @item -fno-access-control
- Turn off all access checking. This switch is mainly useful for working
- around bugs in the access control code.
-
- @item -fall-virtual
- Treat all possible member functions as virtual, implicitly.
- All member functions (except for constructor functions and @code{new} or
- @code{delete} member operators) are treated as virtual functions of the
- class where they appear.
-
- This does not mean that all calls to these member functions will be made
- through the internal table of virtual functions. Under some
- circumstances, the compiler can determine that a call to a given virtual
- function can be made directly; in these cases the calls are direct in
- any case.
-
- @item -fconserve-space
- Put uninitialized or runtime-initialized global variables into the
- common segment, as C does. This saves space in the executable at the
- cost of not diagnosing duplicate definitions. If your program
- mysteriously crashes after @code{main()} has completed, you may have an
- object that is being destroyed twice because two definitions were merged.
-
- @item -fdollars-in-identifiers
- Accept @samp{$} in identifiers. You can also explicitly prohibit use of
- @samp{$} with the option @samp{-fno-dollars-in-identifiers}. (GNU C++
- allows @samp{$} by default on some target systems but not others.)
- Traditional C allowed the character @samp{$} to form part of
- identifiers. However, ANSI C and C++ forbid @samp{$} in identifiers.
-
- @item -fenum-int-equiv
- Permit implicit conversion of @code{int} to enumeration types. Normally
- GNU C++ allows conversion of @code{enum} to @code{int}, but not the
- other way around.
-
- @item -fexternal-templates
- Cause template instantiations to obey @samp{#pragma interface} and
- @samp{implementation}; template instances are emitted or not according
- to the location of the template definition. @xref{Template
- Instantiation}, for more information.
-
- @item -falt-external-templates
- Similar to -fexternal-templates, but template instances are emitted or
- not according to the place where they are first instantiated.
- @xref{Template Instantiation}, for more information.
-
- @item -fno-implicit-templates
- Never emit code for templates which are instantiated implicitly (i.e. by
- use); only emit code for explicit instantiations. @xref{Template
- Instantiation}, for more information.
-
- @item -fhandle-signatures
- Recognize the @code{signature} and @code{sigof} keywords for specifying
- abstract types. The default (@samp{-fno-handle-signatures}) is not to
- recognize them. @xref{C++ Signatures, Type Abstraction using
- Signatures}.
-
- @item -fhuge-objects
- Support virtual function calls for objects that exceed the size
- representable by a @samp{short int}. Users should not use this flag by
- default; if you need to use it, the compiler will tell you so. If you
- compile any of your code with this flag, you must compile @emph{all} of
- your code with this flag (including libg++, if you use it).
-
- This flag is not useful when compiling with -fvtable-thunks.
-
- @item -fno-implement-inlines
- To save space, do not emit out-of-line copies of inline functions
- controlled by @samp{#pragma implementation}. This will cause linker
- errors if these functions are not inlined everywhere they are called.
-
- @item -fmemoize-lookups
- @itemx -fsave-memoized
- Use heuristics to compile faster. These heuristics are not enabled by
- default, since they are only effective for certain input files. Other
- input files compile more slowly.
-
- The first time the compiler must build a call to a member function (or
- reference to a data member), it must (1) determine whether the class
- implements member functions of that name; (2) resolve which member
- function to call (which involves figuring out what sorts of type
- conversions need to be made); and (3) check the visibility of the member
- function to the caller. All of this adds up to slower compilation.
- Normally, the second time a call is made to that member function (or
- reference to that data member), it must go through the same lengthy
- process again. This means that code like this:
-
- @smallexample
- cout << "This " << p << " has " << n << " legs.\n";
- @end smallexample
-
- @noindent
- makes six passes through all three steps. By using a software cache, a
- ``hit'' significantly reduces this cost. Unfortunately, using the cache
- introduces another layer of mechanisms which must be implemented, and so
- incurs its own overhead. @samp{-fmemoize-lookups} enables the software
- cache.
-
- Because access privileges (visibility) to members and member functions
- may differ from one function context to the next, G++ may need to flush
- the cache. With the @samp{-fmemoize-lookups} flag, the cache is flushed
- after every function that is compiled. The @samp{-fsave-memoized} flag
- enables the same software cache, but when the compiler determines that
- the context of the last function compiled would yield the same access
- privileges of the next function to compile, it preserves the cache.
- This is most helpful when defining many member functions for the same
- class: with the exception of member functions which are friends of other
- classes, each member function has exactly the same access privileges as
- every other, and the cache need not be flushed.
-
- @item -fno-strict-prototype
- Treat a function declaration with no arguments, such as @samp{int foo
- ();}, as C would treat it---as saying nothing about the number of
- arguments or their types. Normally, such a declaration in C++ means
- that the function @code{foo} takes no arguments.
-
- This option does not work with operator overloading, which places
- constraints on the parameter types.
-
- @item -fnonnull-objects
- Assume that objects reached through references are not null.
-
- Normally, GNU C++ makes conservative assumptions about objects reached
- through references. For example, the compiler must check that @code{a}
- is not null in code like the following:
-
- @example
- obj &a = g ();
- a.f (2);
- @end example
-
- Checking that references of this sort have non-null values requires
- extra code, however, and it is unnecessary for many programs. You can
- use @w{@samp{-fnonnull-objects}} to omit the checks for null, if your
- program doesn't require checking.
-
- This checking is currently only done for conversions to virtual base classes.
-
- @item -fthis-is-variable
- Permit assignment to @code{this}. The incorporation of user-defined
- free store management into C++ has made assignment to @samp{this} an
- anachronism. Therefore, by default it is invalid to assign to
- @code{this} within a class member function; that is, GNU C++ treats
- @samp{this} in a member function of class @code{X} as a non-lvalue of
- type @samp{X *}. However, for backwards compatibility, you can make it
- valid with @samp{-fthis-is-variable}.
-
- @item -fvtable-thunks
- Use @samp{thunks} to implement the virtual function dispatch table
- (@samp{vtable}). The traditional (cfront-style) approach to
- implementing vtables was to store a pointer to the function and two
- offsets for adjusting the @samp{this} pointer at the call site. Newer
- implementations store a single pointer to a @samp{thunk} function which
- does any necessary adjustment and then calls the target function.
-
- This option also enables a heuristic for controlling emission of
- vtables; if a class has any non-inline virtual functions, the vtable
- will be emitted in the translation unit containing the first one of
- those.
-
- @item -nostdinc++
- Do not search for header files in the standard directories specific to
- C++, but do still search the other standard directories. (This option
- is used when building libg++.)
-
- @item -traditional
- For C++ programs (in addition to the effects that apply to both C and
- C++), this has the same effect as @samp{-fthis-is-variable}.
- @xref{C Dialect Options,, Options Controlling C Dialect}.
- @end table
-
- In addition, these optimization, warning, and code generation options
- have meanings only for C++ programs:
-
- @table @code
- @item -fno-default-inline
- Do not assume @samp{inline} for functions defined inside a class scope.
- @xref{Optimize Options,,Options That Control Optimization}.
-
- @item -Wenum-clash
- @itemx -Woverloaded-virtual
- @itemx -Wtemplate-debugging
- Warnings that apply only to C++ programs. @xref{Warning
- Options,,Options to Request or Suppress Warnings}.
-
- @item +e@var{n}
- Control how virtual function definitions are used, in a fashion
- compatible with @code{cfront} 1.x. @xref{Code Gen Options,,Options for
- Code Generation Conventions}.
- @end table
-
- @node Warning Options
- @section Options to Request or Suppress Warnings
- @cindex options to control warnings
- @cindex warning messages
- @cindex messages, warning
- @cindex suppressing warnings
-
- Warnings are diagnostic messages that report constructions which
- are not inherently erroneous but which are risky or suggest there
- may have been an error.
-
- You can request many specific warnings with options beginning @samp{-W},
- for example @samp{-Wimplicit} to request warnings on implicit
- declarations. Each of these specific warning options also has a
- negative form beginning @samp{-Wno-} to turn off warnings;
- for example, @samp{-Wno-implicit}. This manual lists only one of the
- two forms, whichever is not the default.
-
- These options control the amount and kinds of warnings produced by GNU
- CC:
-
- @table @code
- @cindex syntax checking
- @item -fsyntax-only
- Check the code for syntax errors, but don't do anything beyond that.
-
- @item -w
- Inhibit all warning messages.
-
- @item -Wno-import
- Inhibit warning messages about the use of @samp{#import}.
-
- @item -pedantic
- Issue all the warnings demanded by strict ANSI standard C; reject
- all programs that use forbidden extensions.
-
- Valid ANSI standard C programs should compile properly with or without
- this option (though a rare few will require @samp{-ansi}). However,
- without this option, certain GNU extensions and traditional C features
- are supported as well. With this option, they are rejected.
-
- @samp{-pedantic} does not cause warning messages for use of the
- alternate keywords whose names begin and end with @samp{__}. Pedantic
- warnings are also disabled in the expression that follows
- @code{__extension__}. However, only system header files should use
- these escape routes; application programs should avoid them.
- @xref{Alternate Keywords}.
-
- This option is not intended to be @i{useful}; it exists only to satisfy
- pedants who would otherwise claim that GNU CC fails to support the ANSI
- standard.
-
- Some users try to use @samp{-pedantic} to check programs for strict ANSI
- C conformance. They soon find that it does not do quite what they want:
- it finds some non-ANSI practices, but not all---only those for which
- ANSI C @emph{requires} a diagnostic.
-
- A feature to report any failure to conform to ANSI C might be useful in
- some instances, but would require considerable additional work and would
- be quite different from @samp{-pedantic}. We recommend, rather, that
- users take advantage of the extensions of GNU C and disregard the
- limitations of other compilers. Aside from certain supercomputers and
- obsolete small machines, there is less and less reason ever to use any
- other C compiler other than for bootstrapping GNU CC.
-
- @item -pedantic-errors
- Like @samp{-pedantic}, except that errors are produced rather than
- warnings.
-
- @item -W
- Print extra warning messages for these events:
-
- @itemize @bullet
- @cindex @code{longjmp} warnings
- @item
- A nonvolatile automatic variable might be changed by a call to
- @code{longjmp}. These warnings as well are possible only in
- optimizing compilation.
-
- The compiler sees only the calls to @code{setjmp}. It cannot know
- where @code{longjmp} will be called; in fact, a signal handler could
- call it at any point in the code. As a result, you may get a warning
- even when there is in fact no problem because @code{longjmp} cannot
- in fact be called at the place which would cause a problem.
-
- @item
- A function can return either with or without a value. (Falling
- off the end of the function body is considered returning without
- a value.) For example, this function would evoke such a
- warning:
-
- @smallexample
- @group
- foo (a)
- @{
- if (a > 0)
- return a;
- @}
- @end group
- @end smallexample
-
- @item
- An expression-statement contains no side effects.
-
- @item
- An unsigned value is compared against zero with @samp{<} or @samp{<=}.
-
- @item
- A comparison like @samp{x<=y<=z} appears; this is equivalent to
- @samp{(x<=y ? 1 : 0) <= z}, which is a different interpretation from
- that of ordinary mathematical notation.
-
- @item
- Storage-class specifiers like @code{static} are not the first things in
- a declaration. According to the C Standard, this usage is obsolescent.
-
- @item
- An aggregate has a partly bracketed initializer.
- For example, the following code would evoke such a warning,
- because braces are missing around the initializer for @code{x.h}:
-
- @smallexample
- struct s @{ int f, g; @};
- struct t @{ struct s h; int i; @};
- struct t x = @{ 1, 2, 3 @};
- @end smallexample
- @end itemize
-
- @item -Wimplicit
- Warn whenever a function or parameter is implicitly declared.
-
- @item -Wreturn-type
- Warn whenever a function is defined with a return-type that defaults
- to @code{int}. Also warn about any @code{return} statement with no
- return-value in a function whose return-type is not @code{void}.
-
- @item -Wunused
- Warn whenever a variable is unused aside from its declaration,
- whenever a function is declared static but never defined, whenever a
- label is declared but not used, and whenever a statement computes a
- result that is explicitly not used.
-
- To suppress this warning for a local variable or expression, simply cast
- it to void. This will also work for file-scope variables, but if you
- want to mark them used at the point of definition, you can use this
- macro:
-
- @smallexample
- #define USE(var) \
- static void *const use_##var = (&use_##var, &var, 0)
-
- USE (string);
- @end smallexample
-
- @item -Wswitch
- Warn whenever a @code{switch} statement has an index of enumeral type
- and lacks a @code{case} for one or more of the named codes of that
- enumeration. (The presence of a @code{default} label prevents this
- warning.) @code{case} labels outside the enumeration range also
- provoke warnings when this option is used.
-
- @item -Wcomment
- Warn whenever a comment-start sequence @samp{/*} appears in a comment.
-
- @item -Wtrigraphs
- Warn if any trigraphs are encountered (assuming they are enabled).
-
- @item -Wformat
- Check calls to @code{printf} and @code{scanf}, etc., to make sure that
- the arguments supplied have types appropriate to the format string
- specified.
-
- @item -Wchar-subscripts
- Warn if an array subscript has type @code{char}. This is a common cause
- of error, as programmers often forget that this type is signed on some
- machines.
-
- @item -Wuninitialized
- An automatic variable is used without first being initialized.
-
- These warnings are possible only in optimizing compilation,
- because they require data flow information that is computed only
- when optimizing. If you don't specify @samp{-O}, you simply won't
- get these warnings.
-
- These warnings occur only for variables that are candidates for
- register allocation. Therefore, they do not occur for a variable that
- is declared @code{volatile}, or whose address is taken, or whose size
- is other than 1, 2, 4 or 8 bytes. Also, they do not occur for
- structures, unions or arrays, even when they are in registers.
-
- Note that there may be no warning about a variable that is used only
- to compute a value that itself is never used, because such
- computations may be deleted by data flow analysis before the warnings
- are printed.
-
- These warnings are made optional because GNU CC is not smart
- enough to see all the reasons why the code might be correct
- despite appearing to have an error. Here is one example of how
- this can happen:
-
- @smallexample
- @{
- int x;
- switch (y)
- @{
- case 1: x = 1;
- break;
- case 2: x = 4;
- break;
- case 3: x = 5;
- @}
- foo (x);
- @}
- @end smallexample
-
- @noindent
- If the value of @code{y} is always 1, 2 or 3, then @code{x} is
- always initialized, but GNU CC doesn't know this. Here is
- another common case:
-
- @smallexample
- @{
- int save_y;
- if (change_y) save_y = y, y = new_y;
- @dots{}
- if (change_y) y = save_y;
- @}
- @end smallexample
-
- @noindent
- This has no bug because @code{save_y} is used only if it is set.
-
- Some spurious warnings can be avoided if you declare all the functions
- you use that never return as @code{noreturn}. @xref{Function
- Attributes}.
-
- @item -Wparentheses
- Warn if parentheses are omitted in certain contexts, such
- as when there is an assignment in a context where a truth value
- is expected, or when operators are nested whose precedence people
- often get confused about.
-
- @item -Wenum-clash
- @cindex enumeration clash warnings
- @cindex warning for enumeration conversions
- Warn about conversion between different enumeration types.
- (C++ only).
-
- @item -Wtemplate-debugging
- @cindex template debugging
- When using templates in a C++ program, warn if debugging is not yet
- fully available (C++ only).
-
- @item -Wreorder (C++ only)
- @cindex reordering, warning
- @cindex warning for reordering of member initializers
- Warn when the order of member initializers given in the code does not
- match the order in which they must be executed. For instance:
-
- @smallexample
- struct A @{
- int i;
- int j;
- A(): j (0), i (1) @{ @}
- @};
- @end smallexample
-
- Here the compiler will warn that the member initializers for @samp{i}
- and @samp{j} will be rearranged to match the declaration order of the
- members.
-
- @item -Wall
- All of the above @samp{-W} options combined. These are all the
- options which pertain to usage that we recommend avoiding and that we
- believe is easy to avoid, even in conjunction with macros.
- @end table
-
- The remaining @samp{-W@dots{}} options are not implied by @samp{-Wall}
- because they warn about constructions that we consider reasonable to
- use, on occasion, in clean programs.
-
- @table @code
- @item -Wtraditional
- Warn about certain constructs that behave differently in traditional and
- ANSI C.
-
- @itemize @bullet
- @item
- Macro arguments occurring within string constants in the macro body.
- These would substitute the argument in traditional C, but are part of
- the constant in ANSI C.
-
- @item
- A function declared external in one block and then used after the end of
- the block.
-
- @item
- A @code{switch} statement has an operand of type @code{long}.
- @end itemize
-
- @item -Wshadow
- Warn whenever a local variable shadows another local variable.
-
- @item -Wid-clash-@var{len}
- Warn whenever two distinct identifiers match in the first @var{len}
- characters. This may help you prepare a program that will compile
- with certain obsolete, brain-damaged compilers.
-
- @item -Wlarger-than-@var{len}
- Warn whenever an object of larger than @var{len} bytes is defined.
-
- @item -Wpointer-arith
- Warn about anything that depends on the ``size of'' a function type or
- of @code{void}. GNU C assigns these types a size of 1, for
- convenience in calculations with @code{void *} pointers and pointers
- to functions.
-
- @item -Wbad-function-cast
- Warn whenever a function call is cast to a non-matching type.
- For example, warn if @code{int malloc()} is cast to @code{anything *}.
-
- @item -Wcast-qual
- Warn whenever a pointer is cast so as to remove a type qualifier from
- the target type. For example, warn if a @code{const char *} is cast
- to an ordinary @code{char *}.
-
- @item -Wcast-align
- Warn whenever a pointer is cast such that the required alignment of the
- target is increased. For example, warn if a @code{char *} is cast to
- an @code{int *} on machines where integers can only be accessed at
- two- or four-byte boundaries.
-
- @item -Wwrite-strings
- Give string constants the type @code{const char[@var{length}]} so that
- copying the address of one into a non-@code{const} @code{char *}
- pointer will get a warning. These warnings will help you find at
- compile time code that can try to write into a string constant, but
- only if you have been very careful about using @code{const} in
- declarations and prototypes. Otherwise, it will just be a nuisance;
- this is why we did not make @samp{-Wall} request these warnings.
-
- @item -Wconversion
- Warn if a prototype causes a type conversion that is different from what
- would happen to the same argument in the absence of a prototype. This
- includes conversions of fixed point to floating and vice versa, and
- conversions changing the width or signedness of a fixed point argument
- except when the same as the default promotion.
-
- Also, warn if a negative integer constant expression is implicitly
- converted to an unsigned type. For example, warn about the assignment
- @code{x = -1} if @code{x} is unsigned. But do not warn about explicit
- casts like @code{(unsigned) -1}.
-
- @item -Waggregate-return
- Warn if any functions that return structures or unions are defined or
- called. (In languages where you can return an array, this also elicits
- a warning.)
-
- @item -Wstrict-prototypes
- Warn if a function is declared or defined without specifying the
- argument types. (An old-style function definition is permitted without
- a warning if preceded by a declaration which specifies the argument
- types.)
-
- @item -Wmissing-prototypes
- Warn if a global function is defined without a previous prototype
- declaration. This warning is issued even if the definition itself
- provides a prototype. The aim is to detect global functions that fail
- to be declared in header files.
-
- @item -Wmissing-declarations
- Warn if a global function is defined without a previous declaration.
- Do so even if the definition itself provides a prototype.
- Use this option to detect global functions that are not declared in
- header files.
-
- @item -Wredundant-decls
- Warn if anything is declared more than once in the same scope, even in
- cases where multiple declaration is valid and changes nothing.
-
- @item -Wnested-externs
- Warn if an @code{extern} declaration is encountered within an function.
-
- @item -Winline
- Warn if a function can not be inlined, and either it was declared as inline,
- or else the @samp{-finline-functions} option was given.
-
- @item -Woverloaded-virtual
- @cindex overloaded virtual fn, warning
- @cindex warning for overloaded virtual fn
- Warn when a derived class function declaration may be an error in
- defining a virtual function (C++ only). In a derived class, the
- definitions of virtual functions must match the type signature of a
- virtual function declared in the base class. With this option, the
- compiler warns when you define a function with the same name as a
- virtual function, but with a type signature that does not match any
- declarations from the base class.
-
- @item -Wsynth (C++ only)
- @cindex warning for synthesized methods
- @cindex synthesized methods, warning
- Warn when g++'s synthesis behavior does not match that of cfront. For
- instance:
-
- @smallexample
- struct A @{
- operator int ();
- A& operator = (int);
- @};
-
- main ()
- @{
- A a,b;
- a = b;
- @}
- @end smallexample
-
- In this example, g++ will synthesize a default @samp{A& operator =
- (const A&);}, while cfront will use the user-defined @samp{operator =}.
-
- @item -Werror
- Make all warnings into errors.
- @end table
-
- @node Debugging Options
- @section Options for Debugging Your Program or GNU CC
- @cindex options, debugging
- @cindex debugging information options
-
- GNU CC has various special options that are used for debugging
- either your program or GCC:
-
- @table @code
- @item -g
- Produce debugging information in the operating system's native format
- (stabs, COFF, XCOFF, or DWARF). GDB can work with this debugging
- information.
-
- On most systems that use stabs format, @samp{-g} enables use of extra
- debugging information that only GDB can use; this extra information
- makes debugging work better in GDB but will probably make other debuggers
- crash or
- refuse to read the program. If you want to control for certain whether
- to generate the extra information, use @samp{-gstabs+}, @samp{-gstabs},
- @samp{-gxcoff+}, @samp{-gxcoff}, @samp{-gdwarf+}, or @samp{-gdwarf}
- (see below).
-
- Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
- @samp{-O}. The shortcuts taken by optimized code may occasionally
- produce surprising results: some variables you declared may not exist
- at all; flow of control may briefly move where you did not expect it;
- some statements may not be executed because they compute constant
- results or their values were already at hand; some statements may
- execute in different places because they were moved out of loops.
-
- Nevertheless it proves possible to debug optimized output. This makes
- it reasonable to use the optimizer for programs that might have bugs.
-
- The following options are useful when GNU CC is generated with the
- capability for more than one debugging format.
-
- @item -ggdb
- Produce debugging information in the native format (if that is supported),
- including GDB extensions if at all possible.
-
- @item -gstabs
- Produce debugging information in stabs format (if that is supported),
- without GDB extensions. This is the format used by DBX on most BSD
- systems. On MIPS, Alpha and System V Release 4 systems this option
- produces stabs debugging output which is not understood by DBX or SDB.
- On System V Release 4 systems this option requires the GNU assembler.
-
- @item -gstabs+
- Produce debugging information in stabs format (if that is supported),
- using GNU extensions understood only by the GNU debugger (GDB). The
- use of these extensions is likely to make other debuggers crash or
- refuse to read the program.
-
- @item -gcoff
- Produce debugging information in COFF format (if that is supported).
- This is the format used by SDB on most System V systems prior to
- System V Release 4.
-
- @item -gxcoff
- Produce debugging information in XCOFF format (if that is supported).
- This is the format used by the DBX debugger on IBM RS/6000 systems.
-
- @item -gxcoff+
- Produce debugging information in XCOFF format (if that is supported),
- using GNU extensions understood only by the GNU debugger (GDB). The
- use of these extensions is likely to make other debuggers crash or
- refuse to read the program.
-
- @item -gdwarf
- Produce debugging information in DWARF format (if that is supported).
- This is the format used by SDB on most System V Release 4 systems.
-
- @item -gdwarf+
- Produce debugging information in DWARF format (if that is supported),
- using GNU extensions understood only by the GNU debugger (GDB). The
- use of these extensions is likely to make other debuggers crash or
- refuse to read the program.
-
- @item -g@var{level}
- @itemx -ggdb@var{level}
- @itemx -gstabs@var{level}
- @itemx -gcoff@var{level}
- @itemx -gxcoff@var{level}
- @itemx -gdwarf@var{level}
- Request debugging information and also use @var{level} to specify how
- much information. The default level is 2.
-
- Level 1 produces minimal information, enough for making backtraces in
- parts of the program that you don't plan to debug. This includes
- descriptions of functions and external variables, but no information
- about local variables and no line numbers.
-
- Level 3 includes extra information, such as all the macro definitions
- present in the program. Some debuggers support macro expansion when
- you use @samp{-g3}.
-
- @cindex @code{prof}
- @item -p
- Generate extra code to write profile information suitable for the
- analysis program @code{prof}. You must use this option when compiling
- the source files you want data about, and you must also use it when
- linking.
-
- @cindex @code{gprof}
- @item -pg
- Generate extra code to write profile information suitable for the
- analysis program @code{gprof}. You must use this option when compiling
- the source files you want data about, and you must also use it when
- linking.
-
- @cindex @code{tcov}
- @item -a
- Generate extra code to write profile information for basic blocks, which will
- record the number of times each basic block is executed, the basic block start
- address, and the function name containing the basic block. If @samp{-g} is
- used, the line number and filename of the start of the basic block will also be
- recorded. If not overridden by the machine description, the default action is
- to append to the text file @file{bb.out}.
-
- This data could be analyzed by a program like @code{tcov}. Note,
- however, that the format of the data is not what @code{tcov} expects.
- Eventually GNU @code{gprof} should be extended to process this data.
-
- @item -d@var{letters}
- Says to make debugging dumps during compilation at times specified by
- @var{letters}. This is used for debugging the compiler. The file names
- for most of the dumps are made by appending a word to the source file
- name (e.g. @file{foo.c.rtl} or @file{foo.c.jump}). Here are the
- possible letters for use in @var{letters}, and their meanings:
-
- @table @samp
- @item M
- Dump all macro definitions, at the end of preprocessing, and write no
- output.
- @item N
- Dump all macro names, at the end of preprocessing.
- @item D
- Dump all macro definitions, at the end of preprocessing, in addition to
- normal output.
- @item y
- Dump debugging information during parsing, to standard error.
- @item r
- Dump after RTL generation, to @file{@var{file}.rtl}.
- @item x
- Just generate RTL for a function instead of compiling it. Usually used
- with @samp{r}.
- @item j
- Dump after first jump optimization, to @file{@var{file}.jump}.
- @item s
- Dump after CSE (including the jump optimization that sometimes
- follows CSE), to @file{@var{file}.cse}.
- @item L
- Dump after loop optimization, to @file{@var{file}.loop}.
- @item t
- Dump after the second CSE pass (including the jump optimization that
- sometimes follows CSE), to @file{@var{file}.cse2}.
- @item f
- Dump after flow analysis, to @file{@var{file}.flow}.
- @item c
- Dump after instruction combination, to the file
- @file{@var{file}.combine}.
- @item S
- Dump after the first instruction scheduling pass, to
- @file{@var{file}.sched}.
- @item l
- Dump after local register allocation, to
- @file{@var{file}.lreg}.
- @item g
- Dump after global register allocation, to
- @file{@var{file}.greg}.
- @item R
- Dump after the second instruction scheduling pass, to
- @file{@var{file}.sched2}.
- @item J
- Dump after last jump optimization, to @file{@var{file}.jump2}.
- @item d
- Dump after delayed branch scheduling, to @file{@var{file}.dbr}.
- @item k
- Dump after conversion from registers to stack, to @file{@var{file}.stack}.
- @item a
- Produce all the dumps listed above.
- @item m
- Print statistics on memory usage, at the end of the run, to
- standard error.
- @item p
- Annotate the assembler output with a comment indicating which
- pattern and alternative was used.
- @end table
-
- @item -fpretend-float
- When running a cross-compiler, pretend that the target machine uses the
- same floating point format as the host machine. This causes incorrect
- output of the actual floating constants, but the actual instruction
- sequence will probably be the same as GNU CC would make when running on
- the target machine.
-
- @item -save-temps
- Store the usual ``temporary'' intermediate files permanently; place them
- in the current directory and name them based on the source file. Thus,
- compiling @file{foo.c} with @samp{-c -save-temps} would produce files
- @file{foo.i} and @file{foo.s}, as well as @file{foo.o}.
-
- @item -print-file-name=@var{library}
- Print the full absolute name of the library file @var{library} that
- would be used when linking---and don't do anything else. With this
- option, GNU CC does not compile or link anything; it just prints the
- file name.
-
- @item -print-prog-name=@var{program}
- Like @samp{-print-file-name}, but searches for a program such as @samp{cpp}.
-
- @item -print-libgcc-file-name
- Same as @samp{-print-file-name=libgcc.a}.
-
- This is useful when you use @samp{-nostdlib} but you do want to link
- with @file{libgcc.a}. You can do
-
- @example
- gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
- @end example
- @end table
-
- @node Optimize Options
- @section Options That Control Optimization
- @cindex optimize options
- @cindex options, optimization
-
- These options control various sorts of optimizations:
-
- @table @code
- @item -O
- @itemx -O1
- Optimize. Optimizing compilation takes somewhat more time, and a lot
- more memory for a large function.
-
- Without @samp{-O}, the compiler's goal is to reduce the cost of
- compilation and to make debugging produce the expected results.
- Statements are independent: if you stop the program with a breakpoint
- between statements, you can then assign a new value to any variable or
- change the program counter to any other statement in the function and
- get exactly the results you would expect from the source code.
-
- Without @samp{-O}, the compiler only allocates variables declared
- @code{register} in registers. The resulting compiled code is a little
- worse than produced by PCC without @samp{-O}.
-
- With @samp{-O}, the compiler tries to reduce code size and execution
- time.
-
- When you specify @samp{-O}, the compiler turns on @samp{-fthread-jumps}
- and @samp{-fdefer-pop} on all machines. The compiler turns on
- @samp{-fdelayed-branch} on machines that have delay slots, and
- @samp{-fomit-frame-pointer} on machines that can support debugging even
- without a frame pointer. On some machines the compiler also turns
- on other flags.@refill
-
- @item -O2
- Optimize even more. GNU CC performs nearly all supported optimizations
- that do not involve a space-speed tradeoff. The compiler does not
- perform loop unrolling or function inlining when you specify @samp{-O2}.
- As compared to @samp{-O}, this option increases both compilation time
- and the performance of the generated code.
-
- @samp{-O2} turns on all optional optimizations except for loop unrolling
- and function inlining. It also turns on frame pointer elimination on
- machines where doing so does not interfer with debugging.
-
- @item -O3
- Optimize yet more. @samp{-O3} turns on all optimizations specified by
- @samp{-O2} and also turns on the @samp{inline-functions} option.
-
- @item -O0
- Do not optimize.
-
- If you use multiple @samp{-O} options, with or without level numbers,
- the last such option is the one that is effective.
- @end table
-
- Options of the form @samp{-f@var{flag}} specify machine-independent
- flags. Most flags have both positive and negative forms; the negative
- form of @samp{-ffoo} would be @samp{-fno-foo}. In the table below,
- only one of the forms is listed---the one which is not the default.
- You can figure out the other form by either removing @samp{no-} or
- adding it.
-
- @table @code
- @item -ffloat-store
- Do not store floating point variables in registers, and inhibit other
- options that might change whether a floating point value is taken from a
- register or memory.
-
- This option prevents undesirable excess precision on machines such as
- the 68000 where the floating registers (of the 68881) keep more
- precision than a @code{double} is supposed to have. For most programs,
- the excess precision does only good, but a few programs rely on the
- precise definition of IEEE floating point. Use @samp{-ffloat-store} for
- such programs.
-
- @item -fno-default-inline
- Do not make member functions inline by default merely because they are
- defined inside the class scope (C++ only). Otherwise, when you specify
- @w{@samp{-O}}, member functions defined inside class scope are compiled
- inline by default; i.e., you don't need to add @samp{inline} in front of
- the member function name.
-
- @item -fno-defer-pop
- Always pop the arguments to each function call as soon as that function
- returns. For machines which must pop arguments after a function call,
- the compiler normally lets arguments accumulate on the stack for several
- function calls and pops them all at once.
-
- @item -fforce-mem
- Force memory operands to be copied into registers before doing
- arithmetic on them. This may produce better code by making all
- memory references potential common subexpressions. When they are
- not common subexpressions, instruction combination should
- eliminate the separate register-load. I am interested in hearing
- about the difference this makes.
-
- @item -fforce-addr
- Force memory address constants to be copied into registers before
- doing arithmetic on them. This may produce better code just as
- @samp{-fforce-mem} may. I am interested in hearing about the
- difference this makes.
-
- @item -fomit-frame-pointer
- Don't keep the frame pointer in a register for functions that
- don't need one. This avoids the instructions to save, set up and
- restore frame pointers; it also makes an extra register available
- in many functions. @strong{It also makes debugging impossible on
- some machines.}
-
- @ifset INTERNALS
- On some machines, such as the Vax, this flag has no effect, because
- the standard calling sequence automatically handles the frame pointer
- and nothing is saved by pretending it doesn't exist. The
- machine-description macro @code{FRAME_POINTER_REQUIRED} controls
- whether a target machine supports this flag. @xref{Registers}.@refill
- @end ifset
- @ifclear INTERNALS
- On some machines, such as the Vax, this flag has no effect, because
- the standard calling sequence automatically handles the frame pointer
- and nothing is saved by pretending it doesn't exist. The
- machine-description macro @code{FRAME_POINTER_REQUIRED} controls
- whether a target machine supports this flag. @xref{Registers,,Register
- Usage, gcc.info, Using and Porting GCC}.@refill
- @end ifclear
-
- @item -fno-inline
- Don't pay attention to the @code{inline} keyword. Normally this option
- is used to keep the compiler from expanding any functions inline.
- Note that if you are not optimizing, no functions can be expanded inline.
-
- @item -finline-functions
- Integrate all simple functions into their callers. The compiler
- heuristically decides which functions are simple enough to be worth
- integrating in this way.
-
- If all calls to a given function are integrated, and the function is
- declared @code{static}, then the function is normally not output as
- assembler code in its own right.
-
- @item -fkeep-inline-functions
- Even if all calls to a given function are integrated, and the function
- is declared @code{static}, nevertheless output a separate run-time
- callable version of the function.
-
- @item -fno-function-cse
- Do not put function addresses in registers; make each instruction that
- calls a constant function contain the function's address explicitly.
-
- This option results in less efficient code, but some strange hacks
- that alter the assembler output may be confused by the optimizations
- performed when this option is not used.
-
- @item -ffast-math
- This option allows GCC to violate some ANSI or IEEE rules and/or
- specifications in the interest of optimizing code for speed. For
- example, it allows the compiler to assume arguments to the @code{sqrt}
- function are non-negative numbers and that no floating-point values
- are NaNs.
-
- This option should never be turned on by any @samp{-O} option since
- it can result in incorrect output for programs which depend on
- an exact implementation of IEEE or ANSI rules/specifications for
- math functions.
- @end table
-
- @c following causes underfulls.. they don't look great, but we deal.
- @c --mew 26jan93
- The following options control specific optimizations. The @samp{-O2}
- option turns on all of these optimizations except @samp{-funroll-loops}
- and @samp{-funroll-all-loops}. On most machines, the @samp{-O} option
- turns on the @samp{-fthread-jumps} and @samp{-fdelayed-branch} options,
- but specific machines may handle it differently.
-
- You can use the following flags in the rare cases when ``fine-tuning''
- of optimizations to be performed is desired.
-
- @table @code
- @item -fstrength-reduce
- Perform the optimizations of loop strength reduction and
- elimination of iteration variables.
-
- @item -fthread-jumps
- Perform optimizations where we check to see if a jump branches to a
- location where another comparison subsumed by the first is found. If
- so, the first branch is redirected to either the destination of the
- second branch or a point immediately following it, depending on whether
- the condition is known to be true or false.
-
- @item -fcse-follow-jumps
- In common subexpression elimination, scan through jump instructions
- when the target of the jump is not reached by any other path. For
- example, when CSE encounters an @code{if} statement with an
- @code{else} clause, CSE will follow the jump when the condition
- tested is false.
-
- @item -fcse-skip-blocks
- This is similar to @samp{-fcse-follow-jumps}, but causes CSE to
- follow jumps which conditionally skip over blocks. When CSE
- encounters a simple @code{if} statement with no else clause,
- @samp{-fcse-skip-blocks} causes CSE to follow the jump around the
- body of the @code{if}.
-
- @item -frerun-cse-after-loop
- Re-run common subexpression elimination after loop optimizations has been
- performed.
-
- @item -fexpensive-optimizations
- Perform a number of minor optimizations that are relatively expensive.
-
- @item -fdelayed-branch
- If supported for the target machine, attempt to reorder instructions
- to exploit instruction slots available after delayed branch
- instructions.
-
- @item -fschedule-insns
- If supported for the target machine, attempt to reorder instructions to
- eliminate execution stalls due to required data being unavailable. This
- helps machines that have slow floating point or memory load instructions
- by allowing other instructions to be issued until the result of the load
- or floating point instruction is required.
-
- @item -fschedule-insns2
- Similar to @samp{-fschedule-insns}, but requests an additional pass of
- instruction scheduling after register allocation has been done. This is
- especially useful on machines with a relatively small number of
- registers and where memory load instructions take more than one cycle.
-
- @item -fcaller-saves
- Enable values to be allocated in registers that will be clobbered by
- function calls, by emitting extra instructions to save and restore the
- registers around such calls. Such allocation is done only when it
- seems to result in better code than would otherwise be produced.
-
- This option is enabled by default on certain machines, usually those
- which have no call-preserved registers to use instead.
-
- @item -funroll-loops
- Perform the optimization of loop unrolling. This is only done for loops
- whose number of iterations can be determined at compile time or run time.
- @samp{-funroll-loop} implies both @samp{-fstrength-reduce} and
- @samp{-frerun-cse-after-loop}.
-
- @item -funroll-all-loops
- Perform the optimization of loop unrolling. This is done for all loops
- and usually makes programs run more slowly. @samp{-funroll-all-loops}
- implies @samp{-fstrength-reduce} as well as @samp{-frerun-cse-after-loop}.
-
- @item -fno-peephole
- Disable any machine-specific peephole optimizations.
- @end table
-
- @node Preprocessor Options
- @section Options Controlling the Preprocessor
- @cindex preprocessor options
- @cindex options, preprocessor
-
- These options control the C preprocessor, which is run on each C source
- file before actual compilation.
-
- If you use the @samp{-E} option, nothing is done except preprocessing.
- Some of these options make sense only together with @samp{-E} because
- they cause the preprocessor output to be unsuitable for actual
- compilation.
-
- @table @code
- @item -include @var{file}
- Process @var{file} as input before processing the regular input file.
- In effect, the contents of @var{file} are compiled first. Any @samp{-D}
- and @samp{-U} options on the command line are always processed before
- @samp{-include @var{file}}, regardless of the order in which they are
- written. All the @samp{-include} and @samp{-imacros} options are
- processed in the order in which they are written.
-
- @item -imacros @var{file}
- Process @var{file} as input, discarding the resulting output, before
- processing the regular input file. Because the output generated from
- @var{file} is discarded, the only effect of @samp{-imacros @var{file}}
- is to make the macros defined in @var{file} available for use in the
- main input.
-
- Any @samp{-D} and @samp{-U} options on the command line are always
- processed before @samp{-imacros @var{file}}, regardless of the order in
- which they are written. All the @samp{-include} and @samp{-imacros}
- options are processed in the order in which they are written.
-
- @item -idirafter @var{dir}
- @cindex second include path
- Add the directory @var{dir} to the second include path. The directories
- on the second include path are searched when a header file is not found
- in any of the directories in the main include path (the one that
- @samp{-I} adds to).
-
- @item -iprefix @var{prefix}
- Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix}
- options.
-
- @item -iwithprefix @var{dir}
- Add a directory to the second include path. The directory's name is
- made by concatenating @var{prefix} and @var{dir}, where @var{prefix} was
- specified previously with @samp{-iprefix}. If you have not specified a
- prefix yet, the directory containing the installed passes of the
- compiler is used as the default.
-
- @item -iwithprefixbefore @var{dir}
- Add a directory to the main include path. The directory's name is made
- by concatenating @var{prefix} and @var{dir}, as in the case of
- @samp{-iwithprefix}.
-
- @item -isystem @var{dir}
- Add a directory to the beginning of the second include path, marking it
- as a system directory, so that it gets the same special treatment as
- is applied to the standard system directories.
-
- @item -nostdinc
- Do not search the standard system directories for header files. Only
- the directories you have specified with @samp{-I} options (and the
- current directory, if appropriate) are searched. @xref{Directory
- Options}, for information on @samp{-I}.
-
- By using both @samp{-nostdinc} and @samp{-I-}, you can limit the include-file
- search path to only those directories you specify explicitly.
-
- @item -undef
- Do not predefine any nonstandard macros. (Including architecture flags).
-
- @item -E
- Run only the C preprocessor. Preprocess all the C source files
- specified and output the results to standard output or to the
- specified output file.
-
- @item -C
- Tell the preprocessor not to discard comments. Used with the
- @samp{-E} option.
-
- @item -P
- Tell the preprocessor not to generate @samp{#line} commands.
- Used with the @samp{-E} option.
-
- @cindex make
- @cindex dependencies, make
- @item -M
- Tell the preprocessor to output a rule suitable for @code{make}
- describing the dependencies of each object file. For each source file,
- the preprocessor outputs one @code{make}-rule whose target is the object
- file name for that source file and whose dependencies are all the
- @code{#include} header files it uses. This rule may be a single line or
- may be continued with @samp{\}-newline if it is long. The list of rules
- is printed on standard output instead of the preprocessed C program.
-
- @samp{-M} implies @samp{-E}.
-
- Another way to specify output of a @code{make} rule is by setting
- the environment variable @code{DEPENDENCIES_OUTPUT} (@pxref{Environment
- Variables}).
-
- @item -MM
- Like @samp{-M} but the output mentions only the user header files
- included with @samp{#include "@var{file}"}. System header files
- included with @samp{#include <@var{file}>} are omitted.
-
- @item -MD
- Like @samp{-M} but the dependency information is written to a file made by
- replacing ".c" with ".d" at the end of the input file names.
- This is in addition to compiling the file as specified---@samp{-MD} does
- not inhibit ordinary compilation the way @samp{-M} does.
-
- In Mach, you can use the utility @code{md} to merge multiple dependency
- files into a single dependency file suitable for using with the @samp{make}
- command.
-
- @item -MMD
- Like @samp{-MD} except mention only user header files, not system
- header files.
-
- @item -MG
- Treat missing header files as generated files and assume they live in the
- same directory as the source file. If you specify @samp{-MG}, you
- must also specify either @samp{-M} or @samp{-MM}. @samp{-MG} is not
- supported with @samp{-MD} or @samp{-MMD}.
-
- @item -H
- Print the name of each header file used, in addition to other normal
- activities.
-
- @item -A@var{question}(@var{answer})
- Assert the answer @var{answer} for @var{question}, in case it is tested
- with a preprocessor conditional such as @samp{#if
- #@var{question}(@var{answer})}. @samp{-A-} disables the standard
- assertions that normally describe the target machine.
-
- @item -D@var{macro}
- Define macro @var{macro} with the string @samp{1} as its definition.
-
- @item -D@var{macro}=@var{defn}
- Define macro @var{macro} as @var{defn}. All instances of @samp{-D} on
- the command line are processed before any @samp{-U} options.
-
- @item -U@var{macro}
- Undefine macro @var{macro}. @samp{-U} options are evaluated after all
- @samp{-D} options, but before any @samp{-include} and @samp{-imacros}
- options.
-
- @item -dM
- Tell the preprocessor to output only a list of the macro definitions
- that are in effect at the end of preprocessing. Used with the @samp{-E}
- option.
-
- @item -dD
- Tell the preprocessing to pass all macro definitions into the output, in
- their proper sequence in the rest of the output.
-
- @item -dN
- Like @samp{-dD} except that the macro arguments and contents are omitted.
- Only @samp{#define @var{name}} is included in the output.
-
- @item -trigraphs
- Support ANSI C trigraphs. The @samp{-ansi} option also has this effect.
-
- @item -Wp,@var{option}
- Pass @var{option} as an option to the preprocessor. If @var{option}
- contains commas, it is split into multiple options at the commas.
- @end table
-
- @node Assembler Options
- @section Passing Options to the Assembler
-
- @c prevent bad page break with this line
- You can pass options to the assembler.
-
- @table @code
- @item -Wa,@var{option}
- Pass @var{option} as an option to the assembler. If @var{option}
- contains commas, it is split into multiple options at the commas.
- @end table
-
- @node Link Options
- @section Options for Linking
- @cindex link options
- @cindex options, linking
-
- These options come into play when the compiler links object files into
- an executable output file. They are meaningless if the compiler is
- not doing a link step.
-
- @table @code
- @cindex file names
- @item @var{object-file-name}
- A file name that does not end in a special recognized suffix is
- considered to name an object file or library. (Object files are
- distinguished from libraries by the linker according to the file
- contents.) If linking is done, these object files are used as input
- to the linker.
-
- @item -c
- @itemx -S
- @itemx -E
- If any of these options is used, then the linker is not run, and
- object file names should not be used as arguments. @xref{Overall
- Options}.
-
- @cindex Libraries
- @item -l@var{library}
- Search the library named @var{library} when linking.
-
- It makes a difference where in the command you write this option; the
- linker searches processes libraries and object files in the order they
- are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
- after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
- to functions in @samp{z}, those functions may not be loaded.
-
- The linker searches a standard list of directories for the library,
- which is actually a file named @file{lib@var{library}.a}. The linker
- then uses this file as if it had been specified precisely by name.
-
- The directories searched include several standard system directories
- plus any that you specify with @samp{-L}.
-
- Normally the files found this way are library files---archive files
- whose members are object files. The linker handles an archive file by
- scanning through it for members which define symbols that have so far
- been referenced but not defined. But if the file that is found is an
- ordinary object file, it is linked in the usual fashion. The only
- difference between using an @samp{-l} option and specifying a file name
- is that @samp{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
- and searches several directories.
-
- @item -lobjc
- You need this special case of the @samp{-l} option in order to
- link an Objective C program.
-
- @item -nostartfiles
- Do not use the standard system startup files when linking.
- The standard libraries are used normally.
-
- @item -nostdlib
- Do not use the standard system libraries and startup files when linking.
- Only the files you specify will be passed to the linker.
-
- @cindex @code{-lgcc}, use with @code{-nostdlib}
- @cindex @code{-nostdlib} and unresolved references
- @cindex unresolved references and @code{-nostdlib}
- One of the standard libraries bypassed by @samp{-nostdlib} is
- @file{libgcc.a}, a library of internal subroutines that GNU CC uses to
- overcome shortcomings of particular machines, or special needs for some
- languages.
- @ifset INTERNALS
- (@xref{Interface,,Interfacing to GNU CC Output}, for more discussion of
- @file{libgcc.a}.)
- @end ifset
- @ifclear INTERNALS
- (@xref{Interface,,Interfacing to GNU CC Output,gcc.info,Porting GNU CC},
- for more discussion of @file{libgcc.a}.)
- @end ifclear
- In most cases, you need @file{libgcc.a} even when you want to avoid
- other standard libraries. In other words, when you specify
- @samp{-nostdlib} you should usually specify @samp{-lgcc} as well. This
- ensures that you have no unresolved references to internal GNU CC
- library subroutines. (For example, @samp{__main}, used to ensure C++
- constructors will be called; @pxref{Collect2,,@code{collect2}}.)
-
- @item -s
- Remove all symbol table and relocation information from the executable.
-
- @item -static
- On systems that support dynamic linking, this prevents linking with the shared
- libraries. On other systems, this
- option has no effect.
-
- @item -shared
- Produce a shared object which can then be linked with other objects to
- form an executable. Only a few systems support this option.
-
- @item -symbolic
- Bind references to global symbols when building a shared object. Warn
- about any unresolved references (unless overridden by the link editor
- option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
- this option.
-
- @item -Xlinker @var{option}
- Pass @var{option} as an option to the linker. You can use this to
- supply system-specific linker options which GNU CC does not know how to
- recognize.
-
- If you want to pass an option that takes an argument, you must use
- @samp{-Xlinker} twice, once for the option and once for the argument.
- For example, to pass @samp{-assert definitions}, you must write
- @samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
- @samp{-Xlinker "-assert definitions"}, because this passes the entire
- string as a single argument, which is not what the linker expects.
-
- @item -Wl,@var{option}
- Pass @var{option} as an option to the linker. If @var{option} contains
- commas, it is split into multiple options at the commas.
-
- @item -u @var{symbol}
- Pretend the symbol @var{symbol} is undefined, to force linking of
- library modules to define it. You can use @samp{-u} multiple times with
- different symbols to force loading of additional library modules.
- @end table
-
- @node Directory Options
- @section Options for Directory Search
- @cindex directory options
- @cindex options, directory search
- @cindex search path
-
- These options specify directories to search for header files, for
- libraries and for parts of the compiler:
-
- @table @code
- @item -I@var{dir}
- Append directory @var{dir} to the list of directories searched for
- include files.
-
- @item -I-
- Any directories you specify with @samp{-I} options before the @samp{-I-}
- option are searched only for the case of @samp{#include "@var{file}"};
- they are not searched for @samp{#include <@var{file}>}.
-
- If additional directories are specified with @samp{-I} options after
- the @samp{-I-}, these directories are searched for all @samp{#include}
- directives. (Ordinarily @emph{all} @samp{-I} directories are used
- this way.)
-
- In addition, the @samp{-I-} option inhibits the use of the current
- directory (where the current input file came from) as the first search
- directory for @samp{#include "@var{file}"}. There is no way to
- override this effect of @samp{-I-}. With @samp{-I.} you can specify
- searching the directory which was current when the compiler was
- invoked. That is not exactly the same as what the preprocessor does
- by default, but it is often satisfactory.
-
- @samp{-I-} does not inhibit the use of the standard system directories
- for header files. Thus, @samp{-I-} and @samp{-nostdinc} are
- independent.
-
- @item -L@var{dir}
- Add directory @var{dir} to the list of directories to be searched
- for @samp{-l}.
-
- @item -B@var{prefix}
- This option specifies where to find the executables, libraries,
- include files, and data files of the compiler itself.
-
- The compiler driver program runs one or more of the subprograms
- @file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
- @var{prefix} as a prefix for each program it tries to run, both with and
- without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
-
- For each subprogram to be run, the compiler driver first tries the
- @samp{-B} prefix, if any. If that name is not found, or if @samp{-B}
- was not specified, the driver tries two standard prefixes, which are
- @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}. If neither of
- those results in a file name that is found, the unmodified program
- name is searched for using the directories specified in your
- @samp{PATH} environment variable.
-
- @samp{-B} prefixes that effectively specify directory names also apply
- to libraries in the linker, because the compiler translates these
- options into @samp{-L} options for the linker. They also apply to
- includes files in the preprocessor, because the compiler translates these
- options into @samp{-isystem} options for the preprocessor. In this case,
- the compiler appends @samp{include} to the prefix.
-
- The run-time support file @file{libgcc.a} can also be searched for using
- the @samp{-B} prefix, if needed. If it is not found there, the two
- standard prefixes above are tried, and that is all. The file is left
- out of the link if it is not found by those means.
-
- Another way to specify a prefix much like the @samp{-B} prefix is to use
- the environment variable @code{GCC_EXEC_PREFIX}. @xref{Environment
- Variables}.
- @end table
-
- @node Target Options
- @section Specifying Target Machine and Compiler Version
- @cindex target options
- @cindex cross compiling
- @cindex specifying machine version
- @cindex specifying compiler version and target machine
- @cindex compiler version, specifying
- @cindex target machine, specifying
-
- By default, GNU CC compiles code for the same type of machine that you
- are using. However, it can also be installed as a cross-compiler, to
- compile for some other type of machine. In fact, several different
- configurations of GNU CC, for different target machines, can be
- installed side by side. Then you specify which one to use with the
- @samp{-b} option.
-
- In addition, older and newer versions of GNU CC can be installed side
- by side. One of them (probably the newest) will be the default, but
- you may sometimes wish to use another.
-
- @table @code
- @item -b @var{machine}
- The argument @var{machine} specifies the target machine for compilation.
- This is useful when you have installed GNU CC as a cross-compiler.
-
- The value to use for @var{machine} is the same as was specified as the
- machine type when configuring GNU CC as a cross-compiler. For
- example, if a cross-compiler was configured with @samp{configure
- i386v}, meaning to compile for an 80386 running System V, then you
- would specify @samp{-b i386v} to run that cross compiler.
-
- When you do not specify @samp{-b}, it normally means to compile for
- the same type of machine that you are using.
-
- @item -V @var{version}
- The argument @var{version} specifies which version of GNU CC to run.
- This is useful when multiple versions are installed. For example,
- @var{version} might be @samp{2.0}, meaning to run GNU CC version 2.0.
-
- The default version, when you do not specify @samp{-V}, is controlled
- by the way GNU CC is installed. Normally, it will be a version that
- is recommended for general use.
- @end table
-
- The @samp{-b} and @samp{-V} options actually work by controlling part of
- the file name used for the executable files and libraries used for
- compilation. A given version of GNU CC, for a given target machine, is
- normally kept in the directory @file{/usr/local/lib/gcc-lib/@var{machine}/@var{version}}.@refill
-
- Thus, sites can customize the effect of @samp{-b} or @samp{-V} either by
- changing the names of these directories or adding alternate names (or
- symbolic links). If in directory @file{/usr/local/lib/gcc-lib/} the
- file @file{80386} is a link to the file @file{i386v}, then @samp{-b
- 80386} becomes an alias for @samp{-b i386v}.
-
- In one respect, the @samp{-b} or @samp{-V} do not completely change
- to a different compiler: the top-level driver program @code{gcc}
- that you originally invoked continues to run and invoke the other
- executables (preprocessor, compiler per se, assembler and linker)
- that do the real work. However, since no real work is done in the
- driver program, it usually does not matter that the driver program
- in use is not the one for the specified target and version.
-
- The only way that the driver program depends on the target machine is
- in the parsing and handling of special machine-specific options.
- However, this is controlled by a file which is found, along with the
- other executables, in the directory for the specified version and
- target machine. As a result, a single installed driver program adapts
- to any specified target machine and compiler version.
-
- The driver program executable does control one significant thing,
- however: the default version and target machine. Therefore, you can
- install different instances of the driver program, compiled for
- different targets or versions, under different names.
-
- For example, if the driver for version 2.0 is installed as @code{ogcc}
- and that for version 2.1 is installed as @code{gcc}, then the command
- @code{gcc} will use version 2.1 by default, while @code{ogcc} will use
- 2.0 by default. However, you can choose either version with either
- command with the @samp{-V} option.
-
- @node Submodel Options
- @section Hardware Models and Configurations
- @cindex submodel options
- @cindex specifying hardware config
- @cindex hardware models and configurations, specifying
- @cindex machine dependent options
-
- Earlier we discussed the standard option @samp{-b} which chooses among
- different installed compilers for completely different target
- machines, such as Vax vs. 68000 vs. 80386.
-
- In addition, each of these target machine types can have its own
- special options, starting with @samp{-m}, to choose among various
- hardware models or configurations---for example, 68010 vs 68020,
- floating coprocessor or none. A single installed version of the
- compiler can compile for any model or configuration, according to the
- options specified.
-
- Some configurations of the compiler also support additional special
- options, usually for compatibility with other compilers on the same
- platform.
-
- @ifset INTERNALS
- These options are defined by the macro @code{TARGET_SWITCHES} in the
- machine description. The default for the options is also defined by
- that macro, which enables you to change the defaults.
- @end ifset
-
- @menu
- * M680x0 Options::
- * VAX Options::
- * SPARC Options::
- * Convex Options::
- * AMD29K Options::
- * ARM Options::
- * M88K Options::
- * RS/6000 and PowerPC Options::
- * RT Options::
- * MIPS Options::
- * i386 Options::
- * HPPA Options::
- * Intel 960 Options::
- * DEC Alpha Options::
- * Clipper Options::
- * H8/300 Options::
- * System V Options::
- @end menu
-
- @node M680x0 Options
- @subsection M680x0 Options
- @cindex M680x0 options
-
- These are the @samp{-m} options defined for the 68000 series. The default
- values for these options depends on which style of 68000 was selected when
- the compiler was configured; the defaults for the most common choices are
- given below.
-
- @table @code
- @item -m68000
- @itemx -mc68000
- Generate output for a 68000. This is the default
- when the compiler is configured for 68000-based systems.
-
- @item -m68020
- @itemx -mc68020
- Generate output for a 68020. This is the default
- when the compiler is configured for 68020-based systems.
-
- @item -m68881
- Generate output containing 68881 instructions for floating point.
- This is the default for most 68020 systems unless @samp{-nfp} was
- specified when the compiler was configured.
-
- @item -m68030
- Generate output for a 68030. This is the default when the compiler is
- configured for 68030-based systems.
-
- @item -m68040
- Generate output for a 68040. This is the default when the compiler is
- configured for 68040-based systems.
-
- This option inhibits the use of 68881/68882 instructions that have to be
- emulated by software on the 68040. If your 68040 does not have code to
- emulate those instructions, use @samp{-m68040}.
-
- @item -m68020-40
- Generate output for a 68040, without using any of the new instructions.
- This results in code which can run relatively efficiently on either a
- 68020/68881 or a 68030 or a 68040. The generated code does use the
- 68881 instructions that are emulated on the 68040.
-
- @item -mfpa
- Generate output containing Sun FPA instructions for floating point.
-
- @item -msoft-float
- Generate output containing library calls for floating point.
- @strong{Warning:} the requisite libraries are not part of GNU CC.
- Normally the facilities of the machine's usual C compiler are used, but
- this can't be done directly in cross-compilation. You must make your
- own arrangements to provide suitable library functions for
- cross-compilation.
-
- @item -mshort
- Consider type @code{int} to be 16 bits wide, like @code{short int}.
-
- @item -mnobitfield
- Do not use the bit-field instructions. The @samp{-m68000} option
- implies @w{@samp{-mnobitfield}}.
-
- @item -mbitfield
- Do use the bit-field instructions. The @samp{-m68020} option implies
- @samp{-mbitfield}. This is the default if you use a configuration
- designed for a 68020.
-
- @item -mrtd
- Use a different function-calling convention, in which functions
- that take a fixed number of arguments return with the @code{rtd}
- instruction, which pops their arguments while returning. This
- saves one instruction in the caller since there is no need to pop
- the arguments there.
-
- This calling convention is incompatible with the one normally
- used on Unix, so you cannot use it if you need to call libraries
- compiled with the Unix compiler.
-
- Also, you must provide function prototypes for all functions that
- take variable numbers of arguments (including @code{printf});
- otherwise incorrect code will be generated for calls to those
- functions.
-
- In addition, seriously incorrect code will result if you call a
- function with too many arguments. (Normally, extra arguments are
- harmlessly ignored.)
-
- The @code{rtd} instruction is supported by the 68010 and 68020
- processors, but not by the 68000.
- @end table
-
- @node VAX Options
- @subsection VAX Options
- @cindex VAX options
-
- These @samp{-m} options are defined for the Vax:
-
- @table @code
- @item -munix
- Do not output certain jump instructions (@code{aobleq} and so on)
- that the Unix assembler for the Vax cannot handle across long
- ranges.
-
- @item -mgnu
- Do output those jump instructions, on the assumption that you
- will assemble with the GNU assembler.
-
- @item -mg
- Output code for g-format floating point numbers instead of d-format.
- @end table
-
- @node SPARC Options
- @subsection SPARC Options
- @cindex SPARC options
-
- These @samp{-m} switches are supported on the SPARC:
-
- @table @code
- @item -mno-app-regs
- @itemx -mapp-regs
- Specify @samp{-mapp-regs} to generate output using the global registers
- 2 through 4, which the SPARC SVR4 ABI reserves for applications. This
- is the default.
-
- To be fully SVR4 ABI compliant at the cost of some performance loss,
- specify @samp{-mno-app-regs}. You should compile libraries and system
- software with this option.
-
- @item -mfpu
- @itemx -mhard-float
- Generate output containing floating point instructions. This is the
- default.
-
- @item -mno-fpu
- @itemx -msoft-float
- Generate output containing library calls for floating point.
- @strong{Warning:} there is no GNU floating-point library for SPARC.
- Normally the facilities of the machine's usual C compiler are used, but
- this cannot be done directly in cross-compilation. You must make your
- own arrangements to provide suitable library functions for
- cross-compilation.
-
- @samp{-msoft-float} changes the calling convention in the output file;
- therefore, it is only useful if you compile @emph{all} of a program with
- this option. In particular, you need to compile @file{libgcc.a}, the
- library that comes with GNU CC, with @samp{-msoft-float} in order for
- this to work.
-
- @item -mhard-quad-float
- Generate output containing quad-word (long double) floating point
- instructions.
-
- @item -msoft-quad-float
- Generate output containing library calls for quad-word (long double)
- floating point instructions. The functions called are those specified
- in the SPARC ABI. This is the default.
-
- As of this writing, there are no sparc implementations that have hardware
- support for the quad-word floating point instructions. They all invoke
- a trap handler for one of these instructions, and then the trap handler
- emulates the effect of the instruction. Because of the trap handler overhead,
- this is much slower than calling the ABI library routines. Thus the
- @samp{-msoft-quad-float} option is the default.
-
- @item -mno-epilogue
- @itemx -mepilogue
- With @samp{-mepilogue} (the default), the compiler always emits code for
- function exit at the end of each function. Any function exit in
- the middle of the function (such as a return statement in C) will
- generate a jump to the exit code at the end of the function.
-
- With @samp{-mno-epilogue}, the compiler tries to emit exit code inline
- at every function exit.
-
- @item -mno-flat
- @itemx -mflat
- With @samp{-mflat}, the compiler does not generate save/restore instructions
- and will use a "flat" or single register window calling convention.
- This model uses %i7 as the frame pointer and is compatible with the normal
- register window model. Code from either may be intermixed although
- debugger support is still incomplete. The local registers and the input
- registers (0-5) are still treated as "call saved" registers and will be
- saved on the stack as necessary.
-
- With @samp{-mno-flat} (the default), the compiler emits save/restore
- instructions (except for leaf functions) and is the normal mode of operation.
-
- @item -mno-unaligned-doubles
- @itemx -munaligned-doubles
- Assume that doubles have 8 byte alignment. This is the default.
-
- With @samp{-munaligned-doubles}, GNU CC assumes that doubles have 8 byte
- alignment only if they are contained in another type, or if they have an
- absolute address. Otherwise, it assumes they have 4 byte alignment.
- Specifying this option avoids some rare compatibility problems with code
- generated by other compilers. It is not the default because it results
- in a performance loss, especially for floating point code.
-
- @item -mv8
- @itemx -msparclite
- These two options select variations on the SPARC architecture.
-
- By default (unless specifically configured for the Fujitsu SPARClite),
- GCC generates code for the v7 variant of the SPARC architecture.
-
- @samp{-mv8} will give you SPARC v8 code. The only difference from v7
- code is that the compiler emits the integer multiply and integer
- divide instructions which exist in SPARC v8 but not in SPARC v7.
-
- @samp{-msparclite} will give you SPARClite code. This adds the integer
- multiply, integer divide step and scan (@code{ffs}) instructions which
- exist in SPARClite but not in SPARC v7.
-
- @item -mcypress
- @itemx -msupersparc
- These two options select the processor for which the code is optimised.
-
- With @samp{-mcypress} (the default), the compiler optimizes code for the
- Cypress CY7C602 chip, as used in the SparcStation/SparcServer 3xx series.
- This is also apropriate for the older SparcStation 1, 2, IPX etc.
-
- With @samp{-msupersparc} the compiler optimizes code for the SuperSparc cpu, as
- used in the SparcStation 10, 1000 and 2000 series. This flag also enables use
- of the full SPARC v8 instruction set.
- @end table
-
- In a future version of GCC, these options will very likely be
- renamed to @samp{-mcpu=cypress} and @samp{-mcpu=supersparc}.
-
- These @samp{-m} switches are supported in addition to the above
- on SPARC V9 processors:
-
- @table @code
- @item -mmedlow
- Generate code for the Medium/Low code model: assume a 32 bit address space.
- Programs are statically linked, PIC is not supported. Pointers are still
- 64 bits.
-
- It is very likely that a future version of GCC will rename this option.
-
- @item -mmedany
- Generate code for the Medium/Anywhere code model: assume a 32 bit text
- segment starting at offset 0, and a 32 bit data segment starting anywhere
- (determined at link time). Programs are statically linked, PIC is not
- supported. Pointers are still 64 bits.
-
- It is very likely that a future version of GCC will rename this option.
-
- @item -mint64
- Types long and int are 64 bits.
-
- @item -mlong32
- Types long and int are 32 bits.
-
- @item -mlong64
- @itemx -mint32
- Type long is 64 bits, and type int is 32 bits.
-
- @item -mstack-bias
- @itemx -mno-stack-bias
- With @samp{-mstack-bias}, GNU CC assumes that the stack pointer, and
- frame pointer if present, are offset by -2047 which must be added back
- when making stack frame references.
- Otherwise, assume no such offset is present.
- @end table
-
- @node Convex Options
- @subsection Convex Options
- @cindex Convex options
-
- These @samp{-m} options are defined for Convex:
-
- @table @code
- @item -mc1
- Generate output for C1. The code will run on any Convex machine.
- The preprocessor symbol @code{__convex__c1__} is defined.
-
- @item -mc2
- Generate output for C2. Uses instructions not available on C1.
- Scheduling and other optimizations are chosen for max performance on C2.
- The preprocessor symbol @code{__convex_c2__} is defined.
-
- @item -mc32
- Generate output for C32xx. Uses instructions not available on C1.
- Scheduling and other optimizations are chosen for max performance on C32.
- The preprocessor symbol @code{__convex_c32__} is defined.
-
- @item -mc34
- Generate output for C34xx. Uses instructions not available on C1.
- Scheduling and other optimizations are chosen for max performance on C34.
- The preprocessor symbol @code{__convex_c34__} is defined.
-
- @item -mc38
- Generate output for C38xx. Uses instructions not available on C1.
- Scheduling and other optimizations are chosen for max performance on C38.
- The preprocessor symbol @code{__convex_c38__} is defined.
-
- @item -margcount
- Generate code which puts an argument count in the word preceding each
- argument list. This is compatible with regular CC, and a few programs
- may need the argument count word. GDB and other source-level debuggers
- do not need it; this info is in the symbol table.
-
- @item -mnoargcount
- Omit the argument count word. This is the default.
-
- @item -mvolatile-cache
- Allow volatile references to be cached. This is the default.
-
- @item -mvolatile-nocache
- Volatile references bypass the data cache, going all the way to memory.
- This is only needed for multi-processor code that does not use standard
- synchronization instructions. Making non-volatile references to volatile
- locations will not necessarily work.
-
- @item -mlong32
- Type long is 32 bits, the same as type int. This is the default.
-
- @item -mlong64
- Type long is 64 bits, the same as type long long. This option is useless,
- because no library support exists for it.
- @end table
-
- @node AMD29K Options
- @subsection AMD29K Options
- @cindex AMD29K options
-
- These @samp{-m} options are defined for the AMD Am29000:
-
- @table @code
- @item -mdw
- @kindex -mdw
- @cindex DW bit (29k)
- Generate code that assumes the @code{DW} bit is set, i.e., that byte and
- halfword operations are directly supported by the hardware. This is the
- default.
-
- @item -mndw
- @kindex -mndw
- Generate code that assumes the @code{DW} bit is not set.
-
- @item -mbw
- @kindex -mbw
- @cindex byte writes (29k)
- Generate code that assumes the system supports byte and halfword write
- operations. This is the default.
-
- @item -mnbw
- @kindex -mnbw
- Generate code that assumes the systems does not support byte and
- halfword write operations. @samp{-mnbw} implies @samp{-mndw}.
-
- @item -msmall
- @kindex -msmall
- @cindex memory model (29k)
- Use a small memory model that assumes that all function addresses are
- either within a single 256 KB segment or at an absolute address of less
- than 256k. This allows the @code{call} instruction to be used instead
- of a @code{const}, @code{consth}, @code{calli} sequence.
-
- @item -mnormal
- @kindex -mnormal
- Use the normal memory model: Generate @code{call} instructions only when
- calling functions in the same file and @code{calli} instructions
- otherwise. This works if each file occupies less than 256 KB but allows
- the entire executable to be larger than 256 KB. This is the default.
-
- @item -mlarge
- Always use @code{calli} instructions. Specify this option if you expect
- a single file to compile into more than 256 KB of code.
-
- @item -m29050
- @kindex -m29050
- @cindex processor selection (29k)
- Generate code for the Am29050.
-
- @item -m29000
- @kindex -m29000
- Generate code for the Am29000. This is the default.
-
- @item -mkernel-registers
- @kindex -mkernel-registers
- @cindex kernel and user registers (29k)
- Generate references to registers @code{gr64-gr95} instead of to
- registers @code{gr96-gr127}. This option can be used when compiling
- kernel code that wants a set of global registers disjoint from that used
- by user-mode code.
-
- Note that when this option is used, register names in @samp{-f} flags
- must use the normal, user-mode, names.
-
- @item -muser-registers
- @kindex -muser-registers
- Use the normal set of global registers, @code{gr96-gr127}. This is the
- default.
-
- @item -mstack-check
- @itemx -mno-stack-check
- @kindex -mstack-check
- @cindex stack checks (29k)
- Insert (or do not insert) a call to @code{__msp_check} after each stack
- adjustment. This is often used for kernel code.
-
- @item -mstorem-bug
- @itemx -mno-storem-bug
- @kindex -mstorem-bug
- @cindex storem bug (29k)
- @samp{-mstorem-bug} handles 29k processors which cannot handle the
- separation of a mtsrim insn and a storem instruction (most 29000 chips
- to date, but not the 29050).
-
- @item -mno-reuse-arg-regs
- @itemx -mreuse-arg-regs
- @kindex -mreuse-arg-regs
- @samp{-mno-reuse-arg-regs} tells the compiler to only use incoming argument
- registers for copying out arguments. This helps detect calling a function
- with fewer arguments than it was declared with.
-
- @item -msoft-float
- @kindex -msoft-float
- Generate output containing library calls for floating point.
- @strong{Warning:} the requisite libraries are not part of GNU CC.
- Normally the facilities of the machine's usual C compiler are used, but
- this can't be done directly in cross-compilation. You must make your
- own arrangements to provide suitable library functions for
- cross-compilation.
- @end table
-
- @node ARM Options
- @subsection ARM Options
- @cindex ARM options
-
- These @samp{-m} options are defined for Advanced RISC Machines (ARM)
- architectures:
-
- @table @code
- @item -m2
- @itemx -m3
- @kindex -m2
- @kindex -m3
- These options are identical. Generate code for the ARM2 and ARM3
- processors. This option is the default. You should also use this
- option to generate code for ARM6 processors that are running with a
- 26-bit program counter.
-
- @item -m6
- @kindex -m6
- Generate code for the ARM6 processor when running with a 32-bit program
- counter.
-
- @item -mapcs
- @kindex -mapcs
- Generate a stack frame that is compliant with the ARM Proceedure Call
- Standard for all functions, even if this is not strictly necessary for
- correct execution of the code.
-
- @item -mbsd
- @kindex -mbsd
- This option only applies to RISC iX. Emulate the native BSD-mode
- compiler. This is the default if @samp{-ansi} is not specified.
-
- @item -mxopen
- @kindex -mxopen
- This option only applies to RISC iX. Emulate the native X/Open-mode
- compiler.
-
- @item -mno-symrename
- @kindex -mno-symrename
- This option only applies to RISC iX. Do not run the assembler
- post-processor, @samp{symrename}, after code has been assembled.
- Normally it is necessary to modify some of the standard symbols in
- preparation for linking with the RISC iX C library; this option
- suppresses this pass. The post-processor is never run when the
- compiler is built for cross-compilation.
- @end table
-
- @node M88K Options
- @subsection M88K Options
- @cindex M88k options
-
- These @samp{-m} options are defined for Motorola 88k architectures:
-
- @table @code
- @item -m88000
- @kindex -m88000
- Generate code that works well on both the m88100 and the
- m88110.
-
- @item -m88100
- @kindex -m88100
- Generate code that works best for the m88100, but that also
- runs on the m88110.
-
- @item -m88110
- @kindex -m88110
- Generate code that works best for the m88110, and may not run
- on the m88100.
-
- @item -mbig-pic
- @kindex -mbig-pic
- Obsolete option to be removed from the next revision.
- Use @samp{-fPIC}.
-
- @item -midentify-revision
- @kindex -midentify-revision
- @kindex ident
- @cindex identifying source, compiler (88k)
- Include an @code{ident} directive in the assembler output recording the
- source file name, compiler name and version, timestamp, and compilation
- flags used.
-
- @item -mno-underscores
- @kindex -mno-underscores
- @cindex underscores, avoiding (88k)
- In assembler output, emit symbol names without adding an underscore
- character at the beginning of each name. The default is to use an
- underscore as prefix on each name.
-
- @item -mocs-debug-info
- @itemx -mno-ocs-debug-info
- @kindex -mocs-debug-info
- @kindex -mno-ocs-debug-info
- @cindex OCS (88k)
- @cindex debugging, 88k OCS
- Include (or omit) additional debugging information (about registers used
- in each stack frame) as specified in the 88open Object Compatibility
- Standard, ``OCS''. This extra information allows debugging of code that
- has had the frame pointer eliminated. The default for DG/UX, SVr4, and
- Delta 88 SVr3.2 is to include this information; other 88k configurations
- omit this information by default.
-
- @item -mocs-frame-position
- @kindex -mocs-frame-position
- @cindex register positions in frame (88k)
- When emitting COFF debugging information for automatic variables and
- parameters stored on the stack, use the offset from the canonical frame
- address, which is the stack pointer (register 31) on entry to the
- function. The DG/UX, SVr4, Delta88 SVr3.2, and BCS configurations use
- @samp{-mocs-frame-position}; other 88k configurations have the default
- @samp{-mno-ocs-frame-position}.
-
- @item -mno-ocs-frame-position
- @kindex -mno-ocs-frame-position
- @cindex register positions in frame (88k)
- When emitting COFF debugging information for automatic variables and
- parameters stored on the stack, use the offset from the frame pointer
- register (register 30). When this option is in effect, the frame
- pointer is not eliminated when debugging information is selected by the
- -g switch.
-
- @item -moptimize-arg-area
- @itemx -mno-optimize-arg-area
- @kindex -moptimize-arg-area
- @kindex -mno-optimize-arg-area
- @cindex arguments in frame (88k)
- Control how function arguments are stored in stack frames.
- @samp{-moptimize-arg-area} saves space by optimizing them, but this
- conflicts with the 88open specifications. The opposite alternative,
- @samp{-mno-optimize-arg-area}, agrees with 88open standards. By default
- GNU CC does not optimize the argument area.
-
- @item -mshort-data-@var{num}
- @kindex -mshort-data-@var{num}
- @cindex smaller data references (88k)
- @cindex r0-relative references (88k)
- Generate smaller data references by making them relative to @code{r0},
- which allows loading a value using a single instruction (rather than the
- usual two). You control which data references are affected by
- specifying @var{num} with this option. For example, if you specify
- @samp{-mshort-data-512}, then the data references affected are those
- involving displacements of less than 512 bytes.
- @samp{-mshort-data-@var{num}} is not effective for @var{num} greater
- than 64k.
-
- @item -mserialize-volatile
- @kindex -mserialize-volatile
- @itemx -mno-serialize-volatile
- @kindex -mno-serialize-volatile
- @cindex sequential consistency on 88k
- Do, or don't, generate code to guarantee sequential consistency
- of volatile memory references. By default, consistency is
- guaranteed.
-
- The order of memory references made by the MC88110 processor does
- not always match the order of the instructions requesting those
- references. In particular, a load instruction may execute before
- a preceding store instruction. Such reordering violates
- sequential consistency of volatile memory references, when there
- are multiple processors. When consistency must be guaranteed,
- GNU C generates special instructions, as needed, to force
- execution in the proper order.
-
- The MC88100 processor does not reorder memory references and so
- always provides sequential consistency. However, by default, GNU
- C generates the special instructions to guarantee consistency
- even when you use @samp{-m88100}, so that the code may be run on an
- MC88110 processor. If you intend to run your code only on the
- MC88100 processor, you may use @samp{-mno-serialize-volatile}.
-
- The extra code generated to guarantee consistency may affect the
- performance of your application. If you know that you can safely
- forgo this guarantee, you may use @samp{-mno-serialize-volatile}.
-
- @item -msvr4
- @itemx -msvr3
- @kindex -msvr4
- @kindex -msvr3
- @cindex assembler syntax, 88k
- @cindex SVr4
- Turn on (@samp{-msvr4}) or off (@samp{-msvr3}) compiler extensions
- related to System V release 4 (SVr4). This controls the following:
-
- @enumerate
- @item
- Which variant of the assembler syntax to emit.
- @item
- @samp{-msvr4} makes the C preprocessor recognize @samp{#pragma weak}
- that is used on System V release 4.
- @item
- @samp{-msvr4} makes GNU CC issue additional declaration directives used in
- SVr4.
- @end enumerate
-
- @samp{-msvr4} is the default for the m88k-motorola-sysv4 and
- m88k-dg-dgux m88k configurations. @samp{-msvr3} is the default for all
- other m88k configurations.
-
- @item -mversion-03.00
- @kindex -mversion-03.00
- This option is obsolete, and is ignored.
- @c ??? which asm syntax better for GAS? option there too?
-
- @item -mno-check-zero-division
- @itemx -mcheck-zero-division
- @kindex -mno-check-zero-division
- @kindex -mcheck-zero-division
- @cindex zero division on 88k
- Do, or don't, generate code to guarantee that integer division by
- zero will be detected. By default, detection is guaranteed.
-
- Some models of the MC88100 processor fail to trap upon integer
- division by zero under certain conditions. By default, when
- compiling code that might be run on such a processor, GNU C
- generates code that explicitly checks for zero-valued divisors
- and traps with exception number 503 when one is detected. Use of
- mno-check-zero-division suppresses such checking for code
- generated to run on an MC88100 processor.
-
- GNU C assumes that the MC88110 processor correctly detects all
- instances of integer division by zero. When @samp{-m88110} is
- specified, both @samp{-mcheck-zero-division} and
- @samp{-mno-check-zero-division} are ignored, and no explicit checks for
- zero-valued divisors are generated.
-
- @item -muse-div-instruction
- @kindex -muse-div-instruction
- @cindex divide instruction, 88k
- Use the div instruction for signed integer division on the
- MC88100 processor. By default, the div instruction is not used.
-
- On the MC88100 processor the signed integer division instruction
- div) traps to the operating system on a negative operand. The
- operating system transparently completes the operation, but at a
- large cost in execution time. By default, when compiling code
- that might be run on an MC88100 processor, GNU C emulates signed
- integer division using the unsigned integer division instruction
- divu), thereby avoiding the large penalty of a trap to the
- operating system. Such emulation has its own, smaller, execution
- cost in both time and space. To the extent that your code's
- important signed integer division operations are performed on two
- nonnegative operands, it may be desirable to use the div
- instruction directly.
-
- On the MC88110 processor the div instruction (also known as the
- divs instruction) processes negative operands without trapping to
- the operating system. When @samp{-m88110} is specified,
- @samp{-muse-div-instruction} is ignored, and the div instruction is used
- for signed integer division.
-
- Note that the result of dividing INT_MIN by -1 is undefined. In
- particular, the behavior of such a division with and without
- @samp{-muse-div-instruction} may differ.
-
- @item -mtrap-large-shift
- @itemx -mhandle-large-shift
- @kindex -mtrap-large-shift
- @kindex -mhandle-large-shift
- @cindex bit shift overflow (88k)
- @cindex large bit shifts (88k)
- Include code to detect bit-shifts of more than 31 bits; respectively,
- trap such shifts or emit code to handle them properly. By default GNU CC
- makes no special provision for large bit shifts.
-
- @item -mwarn-passed-structs
- @kindex -mwarn-passed-structs
- @cindex structure passing (88k)
- Warn when a function passes a struct as an argument or result.
- Structure-passing conventions have changed during the evolution of the C
- language, and are often the source of portability problems. By default,
- GNU CC issues no such warning.
- @end table
-
- @node RS/6000 and PowerPC Options
- @subsection IBM RS/6000 and PowerPC Options
- @cindex RS/6000 and PowerPC Options
- @cindex IBM RS/6000 and PowerPC Options
-
- These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
- @table @code
- @item -mpower
- @itemx -mno-power
- @itemx -mpower2
- @itemx -mno-power2
- @itemx -mpowerpc
- @itemx -mno-powerpc
- @itemx -mpowerpc-gpopt
- @itemx -mno-powerpc-gpopt
- @itemx -mpowerpc-gfxopt
- @itemx -mno-powerpc-gfxopt
- @kindex -mpower
- @kindex -mpower2
- @kindex -mpowerpc
- @kindex -mpowerpc-gpopt
- @kindex -mpowerpc-gfxopt
- GNU CC supports two related instruction set architectures for the
- RS/6000 and PowerPC. The @dfn{POWER} instruction set are those
- instructions supported by the @samp{rios} chip set used in the original
- RS/6000 systems and the @dfn{PowerPC} instruction set is the
- architecture of the Motorola MPC6xx microprocessors. The PowerPC
- architecture defines 64-bit instructions, but they are not supported by
- any current processors.
-
- Neither architecture is a subset of the other. However there is a
- large common subset of instructions supported by both. An MQ
- register is included in processors supporting the POWER architecture.
-
- You use these options to specify which instructions are available on the
- processor you are using. The default value of these options is
- determined when configuring GNU CC. Specifying the
- @samp{-mcpu=@var{cpu_type}} overrides the specification of these
- options. We recommend you use that option rather than these.
-
- The @samp{-mpower} option allows GNU CC to generate instructions that
- are found only in the POWER architecture and to use the MQ register.
- Specifying @samp{-mpower2} implies @samp{-power} and also allows GNU CC
- to generate instructions that are present in the POWER2 architecture but
- not the original POWER architecture.
-
- The @samp{-mpowerpc} option allows GNU CC to generate instructions that
- are found only in the 32-bit subset of the PowerPC architecture.
- Specifying @samp{-mpowerpc-gpopt} implies @samp{-mpowerpc} and also allows
- GNU CC to use the optional PowerPC architecture instructions in the
- General Purpose group, including floating-point square root. Specifying
- @samp{-mpowerpc-gfxopt} implies @samp{-mpowerpc} and also allows GNU CC to
- use the optional PowerPC architecture instructions in the Graphics
- group, including floating-point select.
-
- If you specify both @samp{-mno-power} and @samp{-mno-powerpc}, GNU CC
- will use only the instructions in the common subset of both
- architectures plus some special AIX common-mode calls, and will not use
- the MQ register. Specifying both @samp{-mpower} and @samp{-mpowerpc}
- permits GNU CC to use any instruction from either architecture and to
- allow use of the MQ register; specify this for the Motorola MPC601.
-
- @item -mnew-mnemonics
- @itemx -mold-mnemonics
- @kindex -mnew-mnemonics
- @kindex -mold-mnemonics
- Select which mnemonics to use in the generated assembler code.
- @samp{-mnew-mnemonics} requests output that uses the assembler mnemonics
- defined for the PowerPC architecture, while @samp{-mold-mnemonics}
- requests the assembler mnemonics defined for the POWER architecture.
- Instructions defined in only one architecture have only one mnemonic;
- GNU CC uses that mnemonic irrespective of which of thse options is
- specified.
-
- PowerPC assemblers support both the old and new mnemonics, as will later
- POWER assemblers. Current POWER assemblers only support the old
- mnemonics. Specify @samp{-mnew-mnemonics} if you have an assembler that
- supports them, otherwise specify @samp{-mold-mnemonics}.
-
- The default value of these options depends on how GNU CC was configured.
- Specifing @samp{-mcpu=@var{cpu_type}} sometimes overrides the value of
- these option. Unless you are building a cross-compiler, you should
- normally not specify either @samp{-mnew-mnemonics} or
- @samp{-mold-mnemonics}, but should instead accept the default.
-
- @item -mcpu=@var{cpu_type}
- Set architecture type, register usage, choice of mnemonics, and
- instruction scheduling parameters for machine type @var{cpu_type}. By
- default, @var{cpu_type} is the target system defined when GNU CC was
- configured. Supported values for @var{cpu_type} are @samp{rios1},
- @samp{rios2}, @samp{rsc}, @samp{601}, @samp{603}, @samp{604},
- @samp{power}, @samp{powerpc}, and @samp{common}. @samp{-mcpu=power} and
- @samp{-mcpu=powerpc} specify generic POWER and pure PowerPC (i.e., not
- MPC601) architecture machine types, with an appropriate, generic
- processor model assumed for scheduling purposes.@refill
-
- Specifying @samp{-mcpu=rios1}, @samp{-mcpu=rios2}, @samp{-mcpu=rsc}, or
- @samp{-mcpu=power} enables the @samp{-mpower} option and disables the
- @samp{-mpowerpc} option; @samp{-mcpu=601} enables both the
- @samp{-mpower} and @samp{-mpowerpc} options; @samp{-mcpu=603},
- @samp{-mcpu=604}, and @samp{-mcpu=powerpc} enable the @samp{-mpowerpc}
- option and disable the @samp{-mpower} option; @samp{-mcpu=common}
- disables both the @samp{-mpower} and @samp{-mpowerpc} options.@refill
-
- To generate code that will operate on all members of the RS/6000 and
- PowerPC families, specify @samp{-mcpu=common}. In that case, GNU CC
- will use only the instructions in the common subset of both
- architectures plus some special AIX common-mode calls, and will not use
- the MQ register. GNU CC assumes a generic processor model for scheduling
- purposes.
-
- Specifying @samp{-mcpu=rios1}, @samp{-mcpu=rios2}, @samp{-mcpu=rsc}, or
- @samp{-mcpu=power} also disables the @samp{new-mnemonics} option.
- Specifying @samp{-mcpu=601}, @samp{-mcpu=603}, @samp{-mcpu=604}, or
- @samp{-mcpu=powerpc} also enables the @samp{new-mnemonics}
- option.@refill
-
- @item -mfull-toc
- @itemx -mno-fp-in-toc
- @itemx -mno-sum-in-toc
- @itemx -mminimal-toc
- Modify generation of the TOC (Table Of Contents), which is created for
- every executable file. The @samp{-mfull-toc} option is selected by
- default. In that case, GNU CC will allocate at least one TOC entry for
- each unique non-automatic variable reference in your program. GNU CC
- will also place floating-point constants in the TOC. However, only
- 16,384 entries are available in the TOC.
-
- If you receive a linker error message that saying you have overflowed
- the available TOC space, you can reduce the amount of TOC space used
- with the @samp{-mno-fp-in-toc} and @samp{-mno-sum-in-toc} options.
- @samp{-mno-fp-in-toc} prevents GNU CC from putting floating-point
- constants in the TOC and @samp{-mno-sum-in-toc} forces GNU CC to
- generate code to calculate the sum of an address and a constant at
- run-time instead of putting that sum into the TOC. You may specify one
- or both of these options. Each causes GNU CC to produce very slightly
- slower and larger code at the expense of conserving TOC space.
-
- If you still run out of space in the TOC even when you specify both of
- these options, specify @samp{-mminimal-toc} instead. This option causes
- GNU CC to make only one TOC entry for every file. When you specify this
- option, GNU CC will produce code that is slower and larger but which
- uses extremely little TOC space. You may wish to use this option
- only on files that contain less frequently executed code. @refill
- @end table
- @node RT Options
- @subsection IBM RT Options
- @cindex RT options
- @cindex IBM RT options
-
- These @samp{-m} options are defined for the IBM RT PC:
-
- @table @code
- @item -min-line-mul
- Use an in-line code sequence for integer multiplies. This is the
- default.
-
- @item -mcall-lib-mul
- Call @code{lmul$$} for integer multiples.
-
- @item -mfull-fp-blocks
- Generate full-size floating point data blocks, including the minimum
- amount of scratch space recommended by IBM. This is the default.
-
- @item -mminimum-fp-blocks
- Do not include extra scratch space in floating point data blocks. This
- results in smaller code, but slower execution, since scratch space must
- be allocated dynamically.
-
- @cindex @file{varargs.h} and RT PC
- @cindex @file{stdarg.h} and RT PC
- @item -mfp-arg-in-fpregs
- Use a calling sequence incompatible with the IBM calling convention in
- which floating point arguments are passed in floating point registers.
- Note that @code{varargs.h} and @code{stdargs.h} will not work with
- floating point operands if this option is specified.
-
- @item -mfp-arg-in-gregs
- Use the normal calling convention for floating point arguments. This is
- the default.
-
- @item -mhc-struct-return
- Return structures of more than one word in memory, rather than in a
- register. This provides compatibility with the MetaWare HighC (hc)
- compiler. Use the option @samp{-fpcc-struct-return} for compatibility
- with the Portable C Compiler (pcc).
-
- @item -mnohc-struct-return
- Return some structures of more than one word in registers, when
- convenient. This is the default. For compatibility with the
- IBM-supplied compilers, use the option @samp{-fpcc-struct-return} or the
- option @samp{-mhc-struct-return}.
- @end table
-
- @node MIPS Options
- @subsection MIPS Options
- @cindex MIPS options
-
- These @samp{-m} options are defined for the MIPS family of computers:
-
- @table @code
- @item -mcpu=@var{cpu type}
- Assume the defaults for the machine type @var{cpu type} when scheduling
- instructions. The choices for @var{cpu type} are @samp{r2000}, @samp{r3000},
- @samp{r4000}, @samp{r4400}, @samp{r4600}, and @samp{r6000}. While picking a
- specific @var{cpu type} will schedule things appropriately for that
- particular chip, the compiler will not generate any code that does not
- meet level 1 of the MIPS ISA (instruction set architecture) without
- the @samp{-mips2} or @samp{-mips3} switches being used.
-
- @item -mips1
- Issue instructions from level 1 of the MIPS ISA. This is the default.
- @samp{r3000} is the default @var{cpu type} at this ISA level.
-
- @item -mips2
- Issue instructions from level 2 of the MIPS ISA (branch likely, square
- root instructions). @samp{r6000} is the default @var{cpu type} at this
- ISA level.
-
- @item -mips3
- Issue instructions from level 3 of the MIPS ISA (64 bit instructions).
- @samp{r4000} is the default @var{cpu type} at this ISA level.
- This option does not change the sizes of any of the C data types.
-
- @item -mfp32
- Assume that 32 32-bit floating point registers are available. This is
- the default.
-
- @item -mfp64
- Assume that 32 64-bit floating point registers are available. This is
- the default when the @samp{-mips3} option is used.
-
- @item -mgp32
- Assume that 32 32-bit general purpose registers are available. This is
- the default.
-
- @item -mgp64
- Assume that 32 64-bit general purpose registers are available. This is
- the default when the @samp{-mips3} option is used.
-
- @item -mint64
- Types long, int, and pointer are 64 bits. This works only if @samp{-mips3}
- is also specified.
-
- @item -mlong64
- Types long and pointer are 64 bits, and type int is 32 bits.
- This works only if @samp{-mips3} is also specified.
-
- @item -mmips-as
- Generate code for the MIPS assembler, and invoke @file{mips-tfile} to
- add normal debug information. This is the default for all
- platforms except for the OSF/1 reference platform, using the OSF/rose
- object format. If the either of the @samp{-gstabs} or @samp{-gstabs+}
- switches are used, the @file{mips-tfile} program will encapsulate the
- stabs within MIPS ECOFF.
-
- @item -mgas
- Generate code for the GNU assembler. This is the default on the OSF/1
- reference platform, using the OSF/rose object format.
-
- @item -mrnames
- @itemx -mno-rnames
- The @samp{-mrnames} switch says to output code using the MIPS software
- names for the registers, instead of the hardware names (ie, @var{a0}
- instead of @var{$4}). The only known assembler that supports this option
- is the Algorithmics assembler.
-
- @item -mgpopt
- @itemx -mno-gpopt
- The @samp{-mgpopt} switch says to write all of the data declarations
- before the instructions in the text section, this allows the MIPS
- assembler to generate one word memory references instead of using two
- words for short global or static data items. This is on by default if
- optimization is selected.
-
- @item -mstats
- @itemx -mno-stats
- For each non-inline function processed, the @samp{-mstats} switch
- causes the compiler to emit one line to the standard error file to
- print statistics about the program (number of registers saved, stack
- size, etc.).
-
- @item -mmemcpy
- @itemx -mno-memcpy
- The @samp{-mmemcpy} switch makes all block moves call the appropriate
- string function (@samp{memcpy} or @samp{bcopy}) instead of possibly
- generating inline code.
-
- @item -mmips-tfile
- @itemx -mno-mips-tfile
- The @samp{-mno-mips-tfile} switch causes the compiler not
- postprocess the object file with the @file{mips-tfile} program,
- after the MIPS assembler has generated it to add debug support. If
- @file{mips-tfile} is not run, then no local variables will be
- available to the debugger. In addition, @file{stage2} and
- @file{stage3} objects will have the temporary file names passed to the
- assembler embedded in the object file, which means the objects will
- not compare the same. The @samp{-mno-mips-tfile} switch should only
- be used when there are bugs in the @file{mips-tfile} program that
- prevents compilation.
-
- @item -msoft-float
- Generate output containing library calls for floating point.
- @strong{Warning:} the requisite libraries are not part of GNU CC.
- Normally the facilities of the machine's usual C compiler are used, but
- this can't be done directly in cross-compilation. You must make your
- own arrangements to provide suitable library functions for
- cross-compilation.
-
- @item -mhard-float
- Generate output containing floating point instructions. This is the
- default if you use the unmodified sources.
-
- @item -mabicalls
- @itemx -mno-abicalls
- Emit (or do not emit) the pseudo operations @samp{.abicalls},
- @samp{.cpload}, and @samp{.cprestore} that some System V.4 ports use for
- position independent code.
-
- @item -mlong-calls
- @itemx -mno-long-calls
- Do all calls with the @samp{JALR} instruction, which requires
- loading up a function's address into a register before the call.
- You need to use this switch, if you call outside of the current
- 512 megabyte segment to functions that are not through pointers.
-
- @item -mhalf-pic
- @itemx -mno-half-pic
- Put pointers to extern references into the data section and load them
- up, rather than put the references in the text section.
-
- @item -membedded-pic
- @itemx -mno-embedded-pic
- Generate PIC code suitable for some embedded systems. All calls are made
- using PC relative address, and all data is addressed using the $gp register.
- This requires GNU as and GNU ld which do most of the work.
-
- @item -membedded-data
- @itemx -mno-embedded-data
- Allocate variables to the read-only data section first if possible, then
- next in the small data section if possible, otherwise in data. This gives
- slightly slower code than the default, but reduces the amount of RAM required
- when executing, and thus may be preferred for some embedded systems.
-
- @item -G @var{num}
- @cindex smaller data references (MIPS)
- @cindex gp-relative references (MIPS)
- Put global and static items less than or equal to @var{num} bytes into
- the small data or bss sections instead of the normal data or bss
- section. This allows the assembler to emit one word memory reference
- instructions based on the global pointer (@var{gp} or @var{$28}),
- instead of the normal two words used. By default, @var{num} is 8 when
- the MIPS assembler is used, and 0 when the GNU assembler is used. The
- @samp{-G @var{num}} switch is also passed to the assembler and linker.
- All modules should be compiled with the same @samp{-G @var{num}}
- value.
-
- @item -nocpp
- Tell the MIPS assembler to not run it's preprocessor over user
- assembler files (with a @samp{.s} suffix) when assembling them.
- @end table
-
- @ifset INTERNALS
- These options are defined by the macro
- @code{TARGET_SWITCHES} in the machine description. The default for the
- options is also defined by that macro, which enables you to change the
- defaults.
- @end ifset
-
- @node i386 Options
- @subsection Intel 386 Options
- @cindex i386 Options
- @cindex Intel 386 Options
-
- These @samp{-m} options are defined for the i386 family of computers:
-
- @table @code
- @item -m486
- @itemx -mno-486
- Control whether or not code is optimized for a 486 instead of an
- 386. Code generated for an 486 will run on a 386 and vice versa.
-
- @item -mieee-fp
- @itemx -m-no-ieee-fp
- Control whether or not the compiler uses IEEE floating point
- comparisons. These handle correctly the case where the result of a
- comparison is unordered.
-
- @item -msoft-float
- Generate output containing library calls for floating point.
- @strong{Warning:} the requisite libraries are not part of GNU CC.
- Normally the facilities of the machine's usual C compiler are used, but
- this can't be done directly in cross-compilation. You must make your
- own arrangements to provide suitable library functions for
- cross-compilation.
-
- On machines where a function returns floating point results in the 80387
- register stack, some floating point opcodes may be emitted even if
- @samp{-msoft-float} is used.
-
- @item -mno-fp-ret-in-387
- Do not use the FPU registers for return values of functions.
-
- The usual calling convention has functions return values of types
- @code{float} and @code{double} in an FPU register, even if there
- is no FPU. The idea is that the operating system should emulate
- an FPU.
-
- The option @samp{-mno-fp-ret-in-387} causes such values to be returned
- in ordinary CPU registers instead.
-
- @item -mno-fancy-math-387
- Some 387 emulators do not support the @code{sin}, @code{cos} and
- @code{sqrt} instructions for the 387. Specify this option to avoid
- generating those instructions. This option is the default on FreeBSD.
- As of revision 2.6.1, these instructions are not generated unless you
- also use the @samp{-ffast-math} switch.
-
- @item -msvr3-shlib
- @itemx -mno-svr3-shlib
- Control whether GNU CC places uninitialized locals into @code{bss} or
- @code{data}. @samp{-msvr3-shlib} places these locals into @code{bss}.
- These options are meaningful only on System V Release 3.
-
- @item -mno-wide-multiply
- @itemx -mwide-multiply
- Control whether GNU CC uses the @code{mul} and @code{imul} that produce
- 64 bit results in @code{eax:edx} from 32 bit operands to do @code{long
- long} multiplies and 32-bit division by constants.
-
- @item -mreg-alloc=@var{regs}
- Control the default allocation order of integer registers. The
- string @var{regs} is a series of letters specifing a register. The
- supported letters are: @code{a} allocate EAX; @code{b} allocate EBX;
- @code{c} allocate ECX; @code{d} allocate EDX; @code{S} allocate ESI;
- @code{D} allocate EDI; @code{B} allocate EBP.
- @end table
-
- @node HPPA Options
- @subsection HPPA Options
- @cindex HPPA Options
-
- These @samp{-m} options are defined for the HPPA family of computers:
-
- @table @code
- @item -mpa-risc-1-0
- Generate code for a PA 1.0 processor.
-
- @item -mpa-risc-1-1
- Generate code for a PA 1.1 processor.
-
- @item -mjump-in-delay
- Fill delay slots of function calls with unconditional jump instructions
- by modifying the return pointer for the function call to be the target
- of the conditional jump.
-
- @item -mlong-calls
- Generate code which allows calls to functions greater than 256k away from
- the caller when the caller and callee are in the same source file. Do
- not turn this option on unless code refuses to link with "branch out of
- range errors" from the linker.
-
- @item -mdisable-fpregs
- Prevent floating point registers from being used in any manner. This is
- necessary for compiling kernels which perform lazy context switching of
- floating point registers. If you use this option and attempt to perform
- floating point operations, the compiler will abort.
-
- @item -mdisable-indexing
- Prevent the compiler from using indexing address modes. This avoids some
- rather obscure problems when compiling MIG generated code under MACH.
-
- @item -mportable-runtime
- Use the portable calling conventions proposed by HP for ELF systems. Note
- this option also enables @samp{-mlong-calls}.
-
- @item -mgas
- Enable the use of assembler directives only GAS understands.
- @end table
-
- @node Intel 960 Options
- @subsection Intel 960 Options
-
- These @samp{-m} options are defined for the Intel 960 implementations:
-
- @table @code
- @item -m@var{cpu type}
- Assume the defaults for the machine type @var{cpu type} for some of
- the other options, including instruction scheduling, floating point
- support, and addressing modes. The choices for @var{cpu type} are
- @samp{ka}, @samp{kb}, @samp{mc}, @samp{ca}, @samp{cf},
- @samp{sa}, and @samp{sb}.
- The default is
- @samp{kb}.
-
- @item -mnumerics
- @itemx -msoft-float
- The @samp{-mnumerics} option indicates that the processor does support
- floating-point instructions. The @samp{-msoft-float} option indicates
- that floating-point support should not be assumed.
-
- @item -mleaf-procedures
- @itemx -mno-leaf-procedures
- Do (or do not) attempt to alter leaf procedures to be callable with the
- @code{bal} instruction as well as @code{call}. This will result in more
- efficient code for explicit calls when the @code{bal} instruction can be
- substituted by the assembler or linker, but less efficient code in other
- cases, such as calls via function pointers, or using a linker that doesn't
- support this optimization.
-
- @item -mtail-call
- @itemx -mno-tail-call
- Do (or do not) make additional attempts (beyond those of the
- machine-independent portions of the compiler) to optimize tail-recursive
- calls into branches. You may not want to do this because the detection of
- cases where this is not valid is not totally complete. The default is
- @samp{-mno-tail-call}.
-
- @item -mcomplex-addr
- @itemx -mno-complex-addr
- Assume (or do not assume) that the use of a complex addressing mode is a
- win on this implementation of the i960. Complex addressing modes may not
- be worthwhile on the K-series, but they definitely are on the C-series.
- The default is currently @samp{-mcomplex-addr} for all processors except
- the CB and CC.
-
- @item -mcode-align
- @itemx -mno-code-align
- Align code to 8-byte boundaries for faster fetching (or don't bother).
- Currently turned on by default for C-series implementations only.
-
- @ignore
- @item -mclean-linkage
- @itemx -mno-clean-linkage
- These options are not fully implemented.
- @end ignore
-
- @item -mic-compat
- @itemx -mic2.0-compat
- @itemx -mic3.0-compat
- Enable compatibility with iC960 v2.0 or v3.0.
-
- @item -masm-compat
- @itemx -mintel-asm
- Enable compatibility with the iC960 assembler.
-
- @item -mstrict-align
- @itemx -mno-strict-align
- Do not permit (do permit) unaligned accesses.
-
- @item -mold-align
- Enable structure-alignment compatibility with Intel's gcc release version
- 1.3 (based on gcc 1.37). Currently this is buggy in that @samp{#pragma
- align 1} is always assumed as well, and cannot be turned off.
- @end table
-
- @node DEC Alpha Options
- @subsection DEC Alpha Options
-
- These @samp{-m} options are defined for the DEC Alpha implementations:
-
- @table @code
- @item -mno-soft-float
- @itemx -msoft-float
- Use (do not use) the hardware floating-point instructions for
- floating-point operations. When @code{-msoft-float} is specified,
- functions in @file{libgcc1.c} will be used to perform floating-point
- operations. Unless they are replaced by routines that emulate the
- floating-point operations, or compiled in such a way as to call such
- emulations routines, these routines will issue floating-point
- operations. If you are compiling for an Alpha without floating-point
- operations, you must ensure that the library is built so as not to call
- them.
-
- Note that Alpha implementations without floating-point operations are
- required to have floating-point registers.
-
- @item -mfp-reg
- @itemx -mno-fp-regs
- Generate code that uses (does not use) the floating-point register set.
- @code{-mno-fp-regs} implies @code{-msoft-float}. If the floating-point
- register set is not used, floating point operands are passed in integer
- registers as if they were integers and floating-point results are passed
- in $0 instead of $f0. This is a non-standard calling sequence, so any
- function with a floating-point argument or return value called by code
- compiled with @code{-mno-fp-regs} must also be compiled with that
- option.
-
- A typical use of this option is building a kernel that does not use,
- and hence need not save and restore, any floating-point registers.
- @end table
-
- @node Clipper Options
- @subsection Clipper Options
-
- These @samp{-m} options are defined for the Clipper implementations:
-
- @table @code
- @item -mc300
- Produce code for a C300 Clipper processor. This is the default.
-
- @itemx -mc400
- Produce code for a C400 Clipper processor i.e. use floting point
- registers f8..f15.
- @end table
-
- @node H8/300 Options
- @subsection H8/300 Options
-
- These @samp{-m} options are defined for the H8/300 implementations:
-
- @table @code
- @item -mrelax
- Shorten some address references at link time, when possible; uses the
- linker option @samp{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
- ld.info, Using ld}, for a fuller description.
-
- @item -mh
- Generate code for the H8/300H.
- @end table
-
- @node System V Options
- @subsection Options for System V
-
- These additional options are available on System V Release 4 for
- compatibility with other compilers on those systems:
-
- @table @code
- @ignore
- This should say *what the option does* and only then say
- "For compatibility only..."
- @item -G
- On SVr4 systems, @code{gcc} accepts the option @samp{-G} (and passes
- it to the system linker), for compatibility with other compilers.
- However, we suggest you use @samp{-symbolic} or @samp{-shared} as
- appropriate, instead of supplying linker options on the @code{gcc}
- command line.
- @end ignore
-
- @item -Qy
- Identify the versions of each tool used by the compiler, in a
- @code{.ident} assembler directive in the output.
-
- @item -Qn
- Refrain from adding @code{.ident} directives to the output file (this is
- the default).
-
- @item -YP,@var{dirs}
- Search the directories @var{dirs}, and no others, for libraries
- specified with @samp{-l}.
-
- @item -Ym,@var{dir}
- Look in the directory @var{dir} to find the M4 preprocessor.
- The assembler uses this option.
- @c This is supposed to go with a -Yd for predefined M4 macro files, but
- @c the generic assembler that comes with Solaris takes just -Ym.
- @end table
-
- @node Code Gen Options
- @section Options for Code Generation Conventions
- @cindex code generation conventions
- @cindex options, code generation
- @cindex run-time options
-
- These machine-independent options control the interface conventions
- used in code generation.
-
- Most of them have both positive and negative forms; the negative form
- of @samp{-ffoo} would be @samp{-fno-foo}. In the table below, only
- one of the forms is listed---the one which is not the default. You
- can figure out the other form by either removing @samp{no-} or adding
- it.
-
- @table @code
- @item -fpcc-struct-return
- Return ``short'' @code{struct} and @code{union} values in memory like
- longer ones, rather than in registers. This convention is less
- efficient, but it has the advantage of allowing intercallability between
- GNU CC-compiled files and files compiled with other compilers.
-
- The precise convention for returning structures in memory depends
- on the target configuration macros.
-
- Short structures and unions are those whose size and alignment match
- that of some integer type.
-
- @item -freg-struct-return
- Use the convention that @code{struct} and @code{union} values are
- returned in registers when possible. This is more efficient for small
- structures than @samp{-fpcc-struct-return}.
-
- If you specify neither @samp{-fpcc-struct-return} nor its contrary
- @samp{-freg-struct-return}, GNU CC defaults to whichever convention is
- standard for the target. If there is no standard convention, GNU CC
- defaults to @samp{-fpcc-struct-return}, except on targets where GNU CC
- is the principal compiler. In those cases, we can choose the standard,
- and we chose the more efficient register return alternative.
-
- @item -fshort-enums
- Allocate to an @code{enum} type only as many bytes as it needs for the
- declared range of possible values. Specifically, the @code{enum} type
- will be equivalent to the smallest integer type which has enough room.
-
- @item -fshort-double
- Use the same size for @code{double} as for @code{float}.
-
- @item -fshared-data
- Requests that the data and non-@code{const} variables of this
- compilation be shared data rather than private data. The distinction
- makes sense only on certain operating systems, where shared data is
- shared between processes running the same program, while private data
- exists in one copy per process.
-
- @item -fno-common
- Allocate even uninitialized global variables in the bss section of the
- object file, rather than generating them as common blocks. This has the
- effect that if the same variable is declared (without @code{extern}) in
- two different compilations, you will get an error when you link them.
- The only reason this might be useful is if you wish to verify that the
- program will work on other systems which always work this way.
-
- @item -fno-ident
- Ignore the @samp{#ident} directive.
-
- @item -fno-gnu-linker
- Do not output global initializations (such as C++ constructors and
- destructors) in the form used by the GNU linker (on systems where the GNU
- linker is the standard method of handling them). Use this option when
- you want to use a non-GNU linker, which also requires using the
- @code{collect2} program to make sure the system linker includes
- constructors and destructors. (@code{collect2} is included in the GNU CC
- distribution.) For systems which @emph{must} use @code{collect2}, the
- compiler driver @code{gcc} is configured to do this automatically.
-
- @item -finhibit-size-directive
- Don't output a @code{.size} assembler directive, or anything else that
- would cause trouble if the function is split in the middle, and the
- two halves are placed at locations far apart in memory. This option is
- used when compiling @file{crtstuff.c}; you should not need to use it
- for anything else.
-
- @item -fverbose-asm
- Put extra commentary information in the generated assembly code to
- make it more readable. This option is generally only of use to those
- who actually need to read the generated assembly code (perhaps while
- debugging the compiler itself).
-
- @item -fvolatile
- Consider all memory references through pointers to be volatile.
-
- @item -fvolatile-global
- Consider all memory references to extern and global data items to
- be volatile.
-
- @item -fpic
- @cindex global offset table
- @cindex PIC
- Generate position-independent code (PIC) suitable for use in a shared
- library, if supported for the target machine. Such code accesses all
- constant addresses through a global offset table (GOT). If the GOT size
- for the linked executable exceeds a machine-specific maximum size, you
- get an error message from the linker indicating that @samp{-fpic} does
- not work; in that case, recompile with @samp{-fPIC} instead. (These
- maximums are 16k on the m88k, 8k on the Sparc, and 32k on the m68k and
- RS/6000. The 386 has no such limit.)
-
- Position-independent code requires special support, and therefore works
- only on certain machines. For the 386, GNU CC supports PIC for System V
- but not for the Sun 386i. Code generated for the IBM RS/6000 is always
- position-independent.
-
- The GNU assembler does not fully support PIC. Currently, you must use
- some other assembler in order for PIC to work. We would welcome
- volunteers to upgrade GAS to handle this; the first part of the job is
- to figure out what the assembler must do differently.
-
- @item -fPIC
- If supported for the target machine, emit position-independent code,
- suitable for dynamic linking and avoiding any limit on the size of the
- global offset table. This option makes a difference on the m68k, m88k
- and the Sparc.
-
- Position-independent code requires special support, and therefore works
- only on certain machines.
-
- @item -ffixed-@var{reg}
- Treat the register named @var{reg} as a fixed register; generated code
- should never refer to it (except perhaps as a stack pointer, frame
- pointer or in some other fixed role).
-
- @var{reg} must be the name of a register. The register names accepted
- are machine-specific and are defined in the @code{REGISTER_NAMES}
- macro in the machine description macro file.
-
- This flag does not have a negative form, because it specifies a
- three-way choice.
-
- @item -fcall-used-@var{reg}
- Treat the register named @var{reg} as an allocatable register that is
- clobbered by function calls. It may be allocated for temporaries or
- variables that do not live across a call. Functions compiled this way
- will not save and restore the register @var{reg}.
-
- Use of this flag for a register that has a fixed pervasive role in the
- machine's execution model, such as the stack pointer or frame pointer,
- will produce disastrous results.
-
- This flag does not have a negative form, because it specifies a
- three-way choice.
-
- @item -fcall-saved-@var{reg}
- Treat the register named @var{reg} as an allocatable register saved by
- functions. It may be allocated even for temporaries or variables that
- live across a call. Functions compiled this way will save and restore
- the register @var{reg} if they use it.
-
- Use of this flag for a register that has a fixed pervasive role in the
- machine's execution model, such as the stack pointer or frame pointer,
- will produce disastrous results.
-
- A different sort of disaster will result from the use of this flag for
- a register in which function values may be returned.
-
- This flag does not have a negative form, because it specifies a
- three-way choice.
-
- @item +e0
- @itemx +e1
- Control whether virtual function definitions in classes are used to
- generate code, or only to define interfaces for their callers. (C++
- only).
-
- These options are provided for compatibility with @code{cfront} 1.x
- usage; the recommended alternative GNU C++ usage is in flux. @xref{C++
- Interface,,Declarations and Definitions in One Header}.
-
- With @samp{+e0}, virtual function definitions in classes are declared
- @code{extern}; the declaration is used only as an interface
- specification, not to generate code for the virtual functions (in this
- compilation).
-
- With @samp{+e1}, G++ actually generates the code implementing virtual
- functions defined in the code, and makes them publicly visible.
- @end table
-
- @node Environment Variables
- @section Environment Variables Affecting GNU CC
- @cindex environment variables
-
- This section describes several environment variables that affect how GNU
- CC operates. They work by specifying directories or prefixes to use
- when searching for various kinds of files.
-
- @ifclear INTERNALS
- Note that you can also specify places to search using options such as
- @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These
- take precedence over places specified using environment variables, which
- in turn take precedence over those specified by the configuration of GNU
- CC.
- @end ifclear
- @ifset INTERNALS
- Note that you can also specify places to search using options such as
- @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These
- take precedence over places specified using environment variables, which
- in turn take precedence over those specified by the configuration of GNU
- CC. @xref{Driver}.
- @end ifset
-
- @table @code
- @item TMPDIR
- @findex TMPDIR
- If @code{TMPDIR} is set, it specifies the directory to use for temporary
- files. GNU CC uses temporary files to hold the output of one stage of
- compilation which is to be used as input to the next stage: for example,
- the output of the preprocessor, which is the input to the compiler
- proper.
-
- @item GCC_EXEC_PREFIX
- @findex GCC_EXEC_PREFIX
- If @code{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
- names of the subprograms executed by the compiler. No slash is added
- when this prefix is combined with the name of a subprogram, but you can
- specify a prefix that ends with a slash if you wish.
-
- If GNU CC cannot find the subprogram using the specified prefix, it
- tries looking in the usual places for the subprogram.
-
- The default value of @code{GCC_EXEC_PREFIX} is
- @file{@var{prefix}/lib/gcc-lib/@var{machine}/@var{version}/} where
- @var{prefix} is the value of @code{prefix} when you ran the
- @file{configure} script and @var{machine} and @var{version} are the
- configuration name and version number of GNU CC, respectively.
-
- Other prefixes specified with @samp{-B} take precedence over this prefix.
-
- This prefix is also used for finding files such as @file{crt0.o} that are
- used for linking.
-
- In addition, the prefix is used in an unusual way in finding the
- directories to search for header files. For each of the standard
- directories whose name normally begins with @samp{/usr/local/lib/gcc-lib}
- (more precisely, with the value of @code{GCC_INCLUDE_DIR}), GNU CC tries
- replacing that beginning with the specified prefix to produce an
- alternate directory name. Thus, with @samp{-Bfoo/}, GNU CC will search
- @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
- These alternate directories are searched first; the standard directories
- come next.
-
- @item COMPILER_PATH
- @findex COMPILER_PATH
- The value of @code{COMPILER_PATH} is a colon-separated list of
- directories, much like @code{PATH}. GNU CC tries the directories thus
- specified when searching for subprograms, if it can't find the
- subprograms using @code{GCC_EXEC_PREFIX}.
-
- @item LIBRARY_PATH
- @findex LIBRARY_PATH
- The value of @code{LIBRARY_PATH} is a colon-separated list of
- directories, much like @code{PATH}. GNU CC tries the directories thus
- specified when searching for special linker files, if it can't find them
- using @code{GCC_EXEC_PREFIX}. Linking using GNU CC also uses these
- directories when searching for ordinary libraries for the @samp{-l}
- option (but directories specified with @samp{-L} come first).
-
- @item C_INCLUDE_PATH
- @itemx CPLUS_INCLUDE_PATH
- @itemx OBJC_INCLUDE_PATH
- @findex C_INCLUDE_PATH
- @findex CPLUS_INCLUDE_PATH
- @findex OBJC_INCLUDE_PATH
- @c @itemx OBJCPLUS_INCLUDE_PATH
- These environment variables pertain to particular languages. Each
- variable's value is a colon-separated list of directories, much like
- @code{PATH}. When GNU CC searches for header files, it tries the
- directories listed in the variable for the language you are using, after
- the directories specified with @samp{-I} but before the standard header
- file directories.
-
- @item DEPENDENCIES_OUTPUT
- @findex DEPENDENCIES_OUTPUT
- @cindex dependencies for make as output
- If this variable is set, its value specifies how to output dependencies
- for Make based on the header files processed by the compiler. This
- output looks much like the output from the @samp{-M} option
- (@pxref{Preprocessor Options}), but it goes to a separate file, and is
- in addition to the usual results of compilation.
-
- The value of @code{DEPENDENCIES_OUTPUT} can be just a file name, in
- which case the Make rules are written to that file, guessing the target
- name from the source file name. Or the value can have the form
- @samp{@var{file} @var{target}}, in which case the rules are written to
- file @var{file} using @var{target} as the target name.
- @end table
-
- @node Running Protoize
- @section Running Protoize
-
- The program @code{protoize} is an optional part of GNU C. You can use
- it to add prototypes to a program, thus converting the program to ANSI
- C in one respect. The companion program @code{unprotoize} does the
- reverse: it removes argument types from any prototypes that are found.
-
- When you run these programs, you must specify a set of source files as
- command line arguments. The conversion programs start out by compiling
- these files to see what functions they define. The information gathered
- about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
-
- After scanning comes actual conversion. The specified files are all
- eligible to be converted; any files they include (whether sources or
- just headers) are eligible as well.
-
- But not all the eligible files are converted. By default,
- @code{protoize} and @code{unprotoize} convert only source and header
- files in the current directory. You can specify additional directories
- whose files should be converted with the @samp{-d @var{directory}}
- option. You can also specify particular files to exclude with the
- @samp{-x @var{file}} option. A file is converted if it is eligible, its
- directory name matches one of the specified directory names, and its
- name within the directory has not been excluded.
-
- Basic conversion with @code{protoize} consists of rewriting most
- function definitions and function declarations to specify the types of
- the arguments. The only ones not rewritten are those for varargs
- functions.
-
- @code{protoize} optionally inserts prototype declarations at the
- beginning of the source file, to make them available for any calls that
- precede the function's definition. Or it can insert prototype
- declarations with block scope in the blocks where undeclared functions
- are called.
-
- Basic conversion with @code{unprotoize} consists of rewriting most
- function declarations to remove any argument types, and rewriting
- function definitions to the old-style pre-ANSI form.
-
- Both conversion programs print a warning for any function declaration or
- definition that they can't convert. You can suppress these warnings
- with @samp{-q}.
-
- The output from @code{protoize} or @code{unprotoize} replaces the
- original source file. The original file is renamed to a name ending
- with @samp{.save}. If the @samp{.save} file already exists, then
- the source file is simply discarded.
-
- @code{protoize} and @code{unprotoize} both depend on GNU CC itself to
- scan the program and collect information about the functions it uses.
- So neither of these programs will work until GNU CC is installed.
-
- Here is a table of the options you can use with @code{protoize} and
- @code{unprotoize}. Each option works with both programs unless
- otherwise stated.
-
- @table @code
- @item -B @var{directory}
- Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
- usual directory (normally @file{/usr/local/lib}). This file contains
- prototype information about standard system functions. This option
- applies only to @code{protoize}.
-
- @item -c @var{compilation-options}
- Use @var{compilation-options} as the options when running @code{gcc} to
- produce the @samp{.X} files. The special option @samp{-aux-info} is
- always passed in addition, to tell @code{gcc} to write a @samp{.X} file.
-
- Note that the compilation options must be given as a single argument to
- @code{protoize} or @code{unprotoize}. If you want to specify several
- @code{gcc} options, you must quote the entire set of compilation options
- to make them a single word in the shell.
-
- There are certain @code{gcc} arguments that you cannot use, because they
- would produce the wrong kind of output. These include @samp{-g},
- @samp{-O}, @samp{-c}, @samp{-S}, and @samp{-o} If you include these in
- the @var{compilation-options}, they are ignored.
-
- @item -C
- Rename files to end in @samp{.C} instead of @samp{.c}.
- This is convenient if you are converting a C program to C++.
- This option applies only to @code{protoize}.
-
- @item -g
- Add explicit global declarations. This means inserting explicit
- declarations at the beginning of each source file for each function
- that is called in the file and was not declared. These declarations
- precede the first function definition that contains a call to an
- undeclared function. This option applies only to @code{protoize}.
-
- @item -i @var{string}
- Indent old-style parameter declarations with the string @var{string}.
- This option applies only to @code{protoize}.
-
- @code{unprotoize} converts prototyped function definitions to old-style
- function definitions, where the arguments are declared between the
- argument list and the initial @samp{@{}. By default, @code{unprotoize}
- uses five spaces as the indentation. If you want to indent with just
- one space instead, use @samp{-i " "}.
-
- @item -k
- Keep the @samp{.X} files. Normally, they are deleted after conversion
- is finished.
-
- @item -l
- Add explicit local declarations. @code{protoize} with @samp{-l} inserts
- a prototype declaration for each function in each block which calls the
- function without any declaration. This option applies only to
- @code{protoize}.
-
- @item -n
- Make no real changes. This mode just prints information about the conversions
- that would have been done without @samp{-n}.
-
- @item -N
- Make no @samp{.save} files. The original files are simply deleted.
- Use this option with caution.
-
- @item -p @var{program}
- Use the program @var{program} as the compiler. Normally, the name
- @file{gcc} is used.
-
- @item -q
- Work quietly. Most warnings are suppressed.
-
- @item -v
- Print the version number, just like @samp{-v} for @code{gcc}.
- @end table
-
- If you need special compiler options to compile one of your program's
- source files, then you should generate that file's @samp{.X} file
- specially, by running @code{gcc} on that source file with the
- appropriate options and the option @samp{-aux-info}. Then run
- @code{protoize} on the entire set of files. @code{protoize} will use
- the existing @samp{.X} file because it is newer than the source file.
- For example:
-
- @example
- gcc -Dfoo=bar file1.c -aux-info
- protoize *.c
- @end example
-
- @noindent
- You need to include the special files along with the rest in the
- @code{protoize} command, even though their @samp{.X} files already
- exist, because otherwise they won't get converted.
-
- @xref{Protoize Caveats}, for more information on how to use
- @code{protoize} successfully.
-
-